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Abstract 

This document is a companion to the WSDL 2.0 specification (Web Services 
Description Language (WSDL) Version 2.0 Part 1: Core Language [WSDL 2.0 
Core], Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts 
[WSDL 2.0 Adjuncts]). It is intended for readers who wish to have an easier, less 
technical introduction to the main features of the language. 
This primer is only intended to be a starting point toward use of WSDL 2.0, and 
hence does not describe every feature of the language. Users are expected to 
consult the WSDL 2.0 specification if they wish to make use of more sophisticated 
features or techniques. 

Finally, this primer is non-normative. Any specific questions of what WSDL 2.0 
requires or forbids should be referred to the WSDL 2.0 specification. 

Status of this Document 
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This section describes the status of this document at the time of its publication. 
Other documents may supersede this document. A list of current W3C publications 
and the latest revision of this technical report can be found in the W3C technical 
reports index at http://www.w3.org/TR/. 

This is a W3C Last Call Working of Web Services Description Language (WSDL) 
Version 2.0 Part 0: Primer for review by W3C Members and other interested 
parties. It has been produced by the Web Services Description Working Group, 
which is part of the W3C We b Services Activity. This document is published to 
give an opportunity to the community to review the new namespace for WSDL 2.0. 
The Working Group plans to request to move to W3C Proposed Recommendation 
shortly after the end of the Last Call period. 

Individuals are invited to send feedback on this document to the public public-ws- 
desc-comments@w3.org mailing list (public archive) through 15 April 2007. 
The Working Group released a test suite along with an implementation report. 
As a result of implementer and community feedback the Working Group made a 
number of changes since the Candidate Recommendation publication. These 
changes include: 

• Removed sections associated with wsdhfeature and wsdl:property. 

• Added guidance on simple operation dispatch when using the HTTP binding 
or the SOAP binding with the SOAP Response MEP. 

Issues about this document are recorded in the issues list maintained by the 
Working Group. A diff-marked ver sion against the prev ious ver sion of this 
document is available. 

Publication as a Working Draft does not imply endorsement by the W3C 
Membership. This is a draft document and may be updated, replaced or obsoleted 
by other documents at any time. It is inappropriate to cite this document as other 
than work in progress. 

This document is governed by the 24 January 2002 CPP as amended by the W3C 
Patent Policy Transition Procedure. W3C maintains a public list of any patent 
disclosures made in connection with the deliverables of the group; that page also 
includes instructions for disclosing a patent. An individual who has actual 
knowledge of a patent which the individual believes contains Essential Claim(s) 
must disclose the information in accordance with section 6 of the W3C Patent 
Policy. 
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1. Introduction 

1.1 Prerequisites 

This primer assumes that the reader has the following prerequisite knowledge: 

• familiarity with XML (Extensible Markup Language (XML) 1.0 (Second 
Edition) [XML 1.0], XML Information Set [XML information Set]) and XML 
Namespaces (Namespaces in XML [XML Namespaces]); 

• some familiarity with XML Schema (XML Schema Part 1: Structures [XML 
Schema: Structures] XML Schema Part 2: Datatypes [XML Schema: 
Datatypes]); 

• familiarity with basic Web services concepts such as Web service, client, and 
the purpose and function of a Web service description. (For an explanation 
of basic Web services concepts, see Web Services Architecture [WS 
Architecture] Section 1.4 and Web Services Glossary [WS Glossary] 
glossary. However, note the Web Services Architecture document uses the 
slightly more precise terms " requester agent " and " provider agent " instead of 
the terms "client" and "Web service" used in this primer.) 

No previous experience with WSDL is assumed. 

1.2 Structure of this Primer 

Section 2 starts with a hypothetical use case involving a hotel reservation service. 
It proceeds step-by-step through the development of a simple example WSDL 2.0 
document that describes this service: 

• The types element describes the kinds of messages that the service will 
send and receive. 

• The interface element describes what abstract functionality the Web 
service provides. 

• The binding element describes how to access the service. 

• The service element describes where to access the service. 

After presenting the example, it moves on to introduce the WSDL 2.0 infoset, 
schema, and component model. Then it provides more detailed coverage on 
defining message types, interfaces, bindings, and services. 
Section 3 explains the WSDL 2.0 importing mechanisms in great details. 
Section 4 talks about WSDL 2.0 extensibility and various predefined extensions. 
Section 5 covers various topics that may fall outside the scope of WSDL 2.0, but 
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shall provide useful background and best practice guidances that may be useful 
when authoring a WSDL 2.0 document or implementing the WSDL 2.0 
specification. 

1.3 Use of URis and IRIs 

The core specification of WSDL 2.0 supports Internationalized Resource Identifiers 
or IRIs [IETF RFC 3987]. IRIs are a superset of URIs with added support for 
internationalization. The URI syntax [IETF RFC 3986] only allows the use of a 
small set of characters, including upper and lower case letters of the English 
alphabet, European numerals and a few symbols. IRIs allow the use of characters 
from a wider range of language scripts. 

For simplicity, examples throughout this primer only use URIs. If you are interested 
in learning more about the use of IRIs, you might care to read the pa per prepared 
by the W3C Intern ationalization Activity . 

1 .4 Notational Conventions 

This document uses several XML namespaces, some of which are defined by 
standards, and some are application-specific. Namespace names of the general 
form "http://greath.example.com/..." represent application or context-dependent 
URIs [IETF RFC 3986]. Note also that the choice of any namespace prefix is 
arbitrary and not semantically significant (see [XML Information Set]). 
Following the convention for XML syntax summary in [WSDL 2.0 Core], this primer 
uses an informal syntax to describe the XML grammar of a WSDL 2.0 document: 

• The syntax appears as an XML instance, but the values indicate the data 
types instead of values. 

• Characters are appended to elements and attributes as follows: "?" (0 or 1), 
"*" (0 or more), "+" (1 or more). 

• Elements names ending in indicate that elements/attributes irrelevant to 
the context are being omitted. 

2. WSDL 2.0 Basics 

2.1 Getting Started: The GreatH Hotel Example 

This section introduces the basic concepts used in WSDL 2.0 through the 
description of a hypothetical hotel reservation service. We start with a simple 
scenario, and later add more requirements to illustrate how more advanced WSDL 
2.0 features may be used. 

2.1.1 Example Scenario: The GreatH Hotel Reservation Service 
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Hotel GreatH (a fictional hotel) is located in a remote island. It has been relying on 
fax and phone to provide room reservations. Even though the facilities and prices 
at GreatH are better than what its competitor offers, GreatH notices that its 
competitor is getting more customers than GreatH. After research, GreatH realizes 
that this is because the competitor offers a Web service that permits travel agent 
reservation systems to reserve rooms directly over the Internet. GreatH then hires 
us to build a reservation Web service with the following functionality: 

• CheckAvailability. To check availability, the client must specify a check-in 
date, a check-out date, and room type. The Web service will return a room 
rate (a floating point number in USD) if such a room is available, or a zero 
room rate if not. If any input data is invalid, the service should return an error. 
Thus, the service will accept a checkAvaiiabiiity message and return a 

checkAvailabilityResponse Or invalidDataFault message. 

• MakeReservation. To make a reservation, a client must provide a name, 
address, and credit card information, and the service will return a 
confirmation number if the reservation is successful. The service will return 
an error message if the credit card number or any other data field is invalid. 
Thus, the service will accept a makeReservation message and return a 

makeReservationResponse Or invalidCreditCardFault message. 

We know that we will later need to build a complete system that supports 
transactions and secured transmission, but initially we will implement only minimal 
functionality. In fact, to simplify our first example, we will implement only the 
CheckAvailability operation. 

The next several sections proceed step-by-step through the process of developing 
a WSDL 2.0 document that describes the desired Web service. However, for those 
who can't wait to see a complete example, here is the WSDL 2.0 document that 
we'll be creating. 



Example 2-1. WSDL 2.0 Document for the GreatH Web Service (Initial Example) 

<?xml version="l . 0" encoding="utf-8" ?> 
<description 

xmlns="http : //www . w3 . org/ ns/wsdl" 

targetNamespace= "http : //greath . example . com/2004/wsdl/resSvc" 

xmlns : tns= "http : //greath . example . com/2 004 /wsdl/resSvc" 

xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 

xmlns : wsoap= "http : //www. w3 . org /ns/wsdl /soap" 

xmlns : soap="http : //www . w3 . org/2003/ 05/ soap-envelope" 

xmlns :wsdlx= "http: //www. w3 . org/ ns/wsdl -extensions'^ 

<documentation> 

This document describes the GreatH Web service. Additional 
application-level requirements for use of this service -- 
beyond what WSDL 2.0 is able to describe — are available 
at http : //greath . example . com/2 004 /reservation-documentation .html 

</documentation> 
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<types> 

<xs : schema 

xmlns : xs="http : //www . w3 . org/2001 /XMLSchema" 

targetNamespace="http: //greath. example. com/2 004 /schemas/resSvc" 
xmlns="http : //greath. example . com/2004 /schemas/resSvc"> 

<xs : element name="checkAvailability" type="tCheckAvai lability" /> 
<xs : complexType name="tCheckAvailability"> 
<xs : sequence> 

<xs: element name="checkInDate" type="xs : date"/> 
<xs:element name="checkOutDate" type="xs :date"/> 
<xs:element name="roomType" type="xs : string" /> 
</xs : sequence> 
</xs : complexType> 

<xs : element name="checkAvailabilityResponse" type="xs : double"/> 

<xs:element name="invalidDataError" type="xs : string"/> 

</xs : schema> 
</types> 

<interface name = "reservationlnterf ace" > 

<fault name = "invalidDataFault" 

element = "ghns : invalidDataError"/> 

<operation name="dpCheckAvai lability" 

pattern="http : //www .w3.org/ns/wsdl/in-out" 
style="http:/ /www. w3.org/ns/wsdl/style/iri" 
wsdlx:safe = "true"> 
<input messageLabel="In" 

element="ghns : checkAvailability" /> 
<output messageLabel="Out" 

element="ghns : checkAvailabilityResponse" /> 
<outfault ref="tns : invalidDataFault" messageLabel="0ut" /> 
</operation> 

</interf ace> 

<binding name="reservationSOAPBinding" 

interf ace="tns : reservationlnterf ace" 
type="http : / /www . w3 . org /ns/wsdl/ soap" 

wsoap :protocol = "http: //www. w3 .org/2 003/ 05/soap/bindings /HTTP/ "> 

<f ault ref="tns : invalidDataFault" 
wsoap : code="soap : Sender"/> 

<operation ref="tns : opCheckAvailability" 

wsoap :mep="http : //www. w3 .org/ 2 003/ 05/ soap/mep/ soap- response "/> 

</binding> 

<service name="reservationService" 

interf ace="tns : reservationlnterf ace"> 
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<endpoint name=" reservationEndpoint" 

binding="tns : reservationSOAPBinding" 

address ="http : //greath . example . com/ 2 004/ reservation "/> 

</service> 
</description> 



2.1.2 Defining a WSDL 2.0 Target Namespace 

Before writing our WSDL 2.0 document, we need to decide on a WSDL 2.0 target 
namespace URI for it. The WSDL 2.0 target namespace is analogous to an XML 
Schema target namespace. Interface, binding and service names that we define in 
our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, 
and thus will be distinguishable from similar names in a different WSDL 2.0 target 
namespace. (This will become important if using WSDL 2.0's import or interface 
inheritance mechanisms.) 

The value of the WSDL 2.0 target namespace must be an absolute URI. 
Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes 
the Web service that the WSDL 2.0 target namespace is used to describe. For 
example, the GreatH owners should make the WSDL 2.0 document available from 
this URI. (And if a WSDL 2.0 description is split into multiple documents, then the 
WSDL 2.0 target namespace should resolve to a master document that includes all 
the WSDL 2.0 documents needed for that service description.) However, there is no 
absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 processor 
must not depend on it being dereferenceable. 

This recommendation may sound circular, but bear in mind that the client might 
have obtained the WSDL 2.0 document from anywhere - not necessarily an 
authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a 
user should be able to obtain an authoritative version. Since GreatH will be the 
owner of the service, the WSDL 2.0 target namespace URI should refer to a 
location on the GreatH Web site or otherwise within its control. 
Once we have decided on a WSDL 2.0 target namespace URI, we can begin our 
WSDL 2.0 document as the following empty shell. 



Example 2-2. An Initial Empty WSDL 2.0 Document 

<?xml version="l . 0" encoding="utf -8 " ?> 
xmlns="http : //www . w3 . org/ns/wsdl" 

targe tNamespace= "http: //greath . example . com/2 0 04 /wsdl/resSvc" 
xmlns : tns= "http : //greath. example . com/2004 /wsdl/resSvc" 



</description> 



2.1.2.1 Explanation of Example 
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<description 

Every WSDL 2.0 document has a description element as its top-most 
element. This merely acts as a container for the rest of the WSDL 2.0 
document, and is used to declare namespaces that will be used throughout 
the document. 

xmlns="http: //www. w3 . org/ns/wsdl" 

This is the XML namespace for WSDL 2.0 itself. We assign it as the default 
namespace for this example by not defining a prefix for it. In other words, 
any unprefixed elements in this example are expected to be WSDL 2.0 
elements (such as the description element). 

targetNamespace= "http : //greath . example . com/2004/wsdl/resSvc" 

This defines the WSDL 2.0 target namespace that we have chosen for the 
GreatH reservation service, as described above. Note that this is not an 
actual XML namespace declaration. Rather, it is a WSDL 2.0 attribute whose 
purpose is analogous to an XML Schema target namespace. 

xmlns : tns= "http : //greath . example . com/2004/wsdl/resSvc" 

This is an actual XML namespace declaration for use in our GreatH service 
description. Note that this is the same URI that was specified above as the 
value of the targetNamespace attribute. This will allow us later to use the tns: 
prefix in QNames, to refer to the WSDL 2.0 target namespace of the GreatH 
service. (For more on QNames see [XML Namespaces] section 3 Qualified 
Names.) 

Now we can start describing the GreatH service. 
2.1.3 Defining Message Types 

We know that the GreatH service will be sending and receiving messages, so a 
good starting point in describing the service is to define the message types that 
the service will use. We'll use XML Schema to do so, because WSDL 2.0 
processors are likely to support XML Schema at a minimum. However, WSDL 2.0 
does not prohibit the use of some other schema definition language. 
WSDL 2.0 allows message types to be defined directly within the WSDL 2.0 
document, inside the types element, which is a child of the description element. 
(Later we'll see how we can provide the type definitions in a separate document, 
using XML Schema's import mechanism.) The following schema defines 

checkAvailability, checkAvailabilityResponse and invalidDataError message 

types that we'll need. 

In WSDL 2.0, all normal and fault message types must be defined as single 
elements at the topmost level (though of course each element may have any 
amount of substructure inside it). Thus, a message type must not directly consist 
of a sequence of elements or other complex type. 

\\Example 2-3. GreatH Message Types 
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<?xml version="l . 0" encoding="utf-8" ?> 
<description 

xmlns="http : //www . w3 . org/ns/wsdl" 

targe tNamespace= "http : / /greath . example . com/2004 /wsdl/resSvc" 
xmlns : tns= "http : //greath . example . com/ 2 00 4 /wsdl/resSvc" 
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 



<types> 

<xs : schema 

xmlns : xs="http : / /www . w3 . org/2 00 1 /XMLSchema" 

targetNamespace="http : //greath . example . com/2004/schemas/resSvc" 
xmlns="http : / /greath . example . com/2 004/schemas/resSvc"> 

<xs : element name=" checkAvaiiabiiity" type="tCheckAvailability" /> 
<xs :complexType name="tCheckAvailability"> 
<xs : sequence> 

<xs:element name="checkInDate" type="xs : date"/> 
<xs:element name="checkOutDate" type="xs : date" /> 
<xs:element name="roomType" type="xs : string" /> 
</xs : sequence> 
</xs : complexType> 

<xs : element name="checkAvailabilityResponse" type="xs : double "/> 

<xs:element name=" invalidDataError " type="xs : string"/> 

</xs : schema> 
</types> 

</description> 



2.1.3.1 Explanation of Example 

xmlns :ghns = "http://greath.example.com/2004/schemas/resSvc" 

We've added another namespace declaration. The ghns namespace prefix will 
allow us (later, when defining an interface) to reference the XML Schema 
target namespace that we define for our message types. Thus, the URI we 
specify must be the same as the URI that we define as the target namespace 
of our XML Schema types (below) -- not the target namespace of the WSDL 
2.0 document itself. 

targetNamespace="http : //greath . example . com/2004/schemas/resSvc" 

This is the XML Schema target namespace that we've created for use by the 
GreatH reservation service. The checkAvaiiabiiity, 

checkAvailabilityResponse and invalidDataError element names Will be 

associated with this XML Schema target namespace. 

checkAvaiiabiiity, checkAvailabilityResponse and invalidDataError 
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These are the message types that we'll use. Note that these are defined to 
be XML elements, as explained above. 

Although we have defined several types, we have not yet indicated which ones are 
to be used as message types for a Web service. We'll do that in the next section. 

2.1.4 Defining an Interface 

WSDL 2.0 enables one to separate the description of a Web service's abstract 
functionality from the concrete details of how and where that functionality is 
offered. This separation facilitates different levels of reusability and distribution of 
work in the lifecycle of a Web service and the WSDL 2.0 document that describes 
it. 

A WSDL 2.0 interface defines the abstract interface of a Web service as a set of 
abstract operations, each operation representing a simple interaction between the 
client and the service. Each operation specifies the types of messages that the 
service can send or receive as part of that operation. Each operation also specifies 
a message exchange pattern that indicates the sequence in which the associated 
messages are to be transmitted between the parties. For example, the in-out 
pattern (see WSDL 2.0 Predefined Extensions [WSDL 2.0 Adjuncts] section 2.2.3 
In-O.ut) indicates that if the client sends a message in to the service, the service 
will either send a reply message back out to the client (in the normal case) or it will 
send a fault message back to the client (in the case of an error). We will explain 
more about message exchange patterns in 2.4.4.3 Understanding Message 
Exchange Patterns (MEPs) 

For the GreatH service, we will (initially) define an interface containing a single 

Operation, opCheckAvailability, Using the checkAvailability and 

checkAvaiiabiiityResponse message types that we defined in the types section. 
We'll use the in-out pattern for this operation, because this is the most natural way 
to represent a simple request-response interaction. We could have instead (for 
example) defined two separate operations using the hvonjy and out-only patterns 
(see WSDL 2.0 Predefined Extensions [WSDL 2.0 Adjuncts] section 2.2.1 In-Only 
and section 2.2.5 Out-Only), but that would just complicate matters for the client, 
because we would then have to separately indicate to the client developer that the 
two operations should be used together as a request-response pair. 
In addition to the normal input and output messages, we also need to specify the 
fault message that we wish to use in the event of an error. WSDL 2.0 permits fault 
messages to be declared within the interface element in order to facilitate reuse 
of faults across operations. If a fault occurs, it terminates whatever message 
sequence was indicated by the message exchange pattern of the operation. 
Let's add these to our WSDL 2.0 document. 



Example 2-4. GreatH Interface Definition 

nl er i t "1 " e li ="utf-8 
I <description 
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II 

xmlns="http : //www . w3 . org/ns/wsdl" 

targetNamespace= "http : / /greath . example . com/2004 /wsdl/resSvc" 
xmlns : tns= "http : //greath .example . com/2004 /wsdl/resSvc" 
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 

xmlns : wsdlx="http : //www.w3 . org/ns/wsdl-extensions"> 



<types> 
</types> 

<interface name = "reservationlnterf ace" > 

<fault name = "invalidDataFault" 

element = "ghns : invalidDataError " /> 

<operation name="opCheckAvail ability" 

pattern="http : //www. w3 . org/ns/wsdl /in-out" 
style="http: //www.w3 .org/ns/wsdl/style/iri" 
wsdlx:safe = "true"> 
<input messageLabel="In" 

element="ghns : checkAvailability" /> 
<output messageLabel="Out" 

element="ghns : checkAvailabilityResponse" /> 
<outfault ref="tns : invalidDataFault" messageLabel="Out"/> 
</ operation> 

</ interf ace> 



</de script ion> 



2.1.4.1 Explanation of Example 

<interface name = "reservationlnterf ace" > 

Interfaces are declared directly inside the description element. In this 
example, we are declaring only one interface, but in general a WSDL 2.0 
document may declare more than one interface. Thus, each interface must be 
given a name that is unique within the set of interfaces defined in this WSDL 
2.0 target namespace. Interface names are tokens that must not contain a 
space or colon (":"). 

<fault name — "invalidDataFault" 

The name attribute defines a name for this fault. The name is required so that 
when an operation is defined, it can reference the desired fault by name. Fault 
names must be unique within an interface. 

element = "ghns : invalidDataError"/> 

The element attribute specifies the schema type of the fault message, as 
previously defined in the types section. 
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<operation name="opCheckAvailability" 

The name attribute defines a name for this operation, so that it can be 
referenced later when bindings are defined. Operation names must also be 
unique within an interface. (WSDL 2.0 uses separate symbol spaces for 
operation and fault names, so operation name "foo" is distinct from fault 
name "foo".) 

pattern="http: //www . w3 . org/ns/wsdl/in-out" 

This line specifies that this operation will use the in-put pattern as described 
above. WSDL 2.0 uses URIs to identify message exchange patterns in order 
to ensure that the identifiers are globally unambiguous, while also permitting 
future new patterns to be defined by anyone. (However, just because 
someone defines a new pattern and creates a URI to identify it, that does not 
mean that other WSDL 2.0 processors will automatically recognize or 
understand that pattern. As with any other extension, it can only be used 
among processors that do recognize and understand it.) 

style="http: //www. w3 . org/ns/wsdl/style/iri" 

This line indicates that the XML schema defining the input message of this 
operation follows a set of rules as specified in IRI I Style that ensures the 
message can be serialized as an IRI. 

wsdlx: safe="true" > 

This line indicates that this operation will not obligate the client in any way, 
i.e., the client can safely invoke this operation without fear that it may be 
incurring an obligation (such as agreeing to buy something). This is further 
explained in 2.4.4 Interface O perations . 

<input messageLabel="In" 

The input element specifies an input message. Even though we have 
already specified which message exchange pattern the operation will use, a 
message exchange pattern represents a template for a message sequence, 
and in theory could consist of multiple input and/or output messages. Thus 
we must also indicate which potential input message in the pattern this 
particular input message represents. This is the purpose of the messageLabei 
attribute. Since the in-out pattern that we've chosen to use only has one 
input message, it is trivial in this case: we simply fill in the message label "In" 
that was defined in WSDL 2.0 Predefined Extensions \WSDL 2.0 Adjuncts ] 
section 2.2.3 In-Out for the in-out pattern. However, if a new pattern is 
defined that involve multiple input messages, then the different input 
messages in the pattern could then be distinguished by using different 
labels. 

element="ghns : checkAvailability" /> 

This specifies the message type for this input message, as defined 
previously in the types section. 

<output messageLabel="Out" . . . 

This is similar to defining an input message. 
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<outfault ref="tns:invalidDataFault" messageLabel="Out"/> 

This associates an output fault with this operation. Faults are declared a little 
differently than normal messages. The ref attribute refers to the name of a 
previously defined fault in this interface -- not a message schema type 
directly. Since message exchange patterns could in general involve a 
sequence of several messages, a fault could potentially occur at various 
points within the message sequence. Because one may wish to associate a 
different fault with each permitted point in the sequence, the messageLabei is 
used to indicate the desired point for this particular fault. It does so indirectly 
by specifying the message that will either trigger this fault or that this fault will 
replace, depending on the pattern. (Some patterns use a mess^e-triggers- 
faul t ru le; others use a f ault- replaces-message rule. See WSDL 2.0 
Predefined Extensions [WSDL 2.0 Adjuncts] section 2.1.2 M e s sa ge Triggers 
Fault and section 2.1.1 Fault Replaces Message.) 

Now that we've defined the abstract interface for the GreatH service, we're ready 
to define a binding for it. 

2.1.5 Defining a Binding 

Although we have specified what abstract messages can be exchanged with the 
GreatH Web service, we have not yet specified how those messages can be 
exchanged. This is the purpose of a binding. A binding specifies concrete 
message format and transmission protocol details for an interface, and must 
supply such details for every operation and fault in the interface. 
In the general case, binding details for each operation and fault are specified using 
operation and fault elements inside a binding element, as shown in the example 
below. However, in some cases it is possible to use defaulting rules to supply the 
information. The WSDL 2.0 SOAP binding extension, for example, defines some 
defaulting rules for operations. (See Web Services Description Language (WSDL) 
Version 2.0 Part 2: Adjuncts [WSDL 2.0 Adjuncts], Default Binding R ules .) 
In order to accommodate new kinds of message formats and transmission 
protocols, bindings are defined using extensions to the WSDL 2.0 language, via 
WSDL 2.0's open content model. (See 4.1 Extensibility for more on extensibility.) 
WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines binding extensions for SOAP 1 .2 
[SOAP 1 .2 Part 1: Messagi ng Framework ] and HTTP 1.1 [I ETF RFC 2616 ] as 
predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily 
defined in WSDL 2.0 documents. However, other specifications could define new 
binding extensions that could also be used to define bindings. (As with any 
extension, other WSDL 2.0 processors would have to know about the new 
constructs in order to make use of them.) 

For the GreatH service, we will use SOAP 1 .2 as our concrete message format 
and HTTP as our underlying transmission protocol, as shown below. 

Example 2-5. GreatH Binding Definition 



http://www.w3.org/TR/2007/WD-wsdl20-primer-20070326/ 



5/8/2007 



Web Services Description Language (WSDL) Version 2.0 Part 0: Primer 



Page 16 of 85 



<?xml version="l . 0" encoding="utf-8" ?> 
<description 

xmlns="http : //www . w3 . org/ns/wsdl" 

targetNamespace= "http: / /greath . example . com/2004 /wsdl/resSvc" 
xmlns : tns= "http : //greath . example . com/20 04 /wsdl/resSvc" 
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 
xmlns :wsoap= "http: //www . w3 . org/ns/wsdl /soap" 
xmlns : soap="http : //www. w3 . org/2003/05/soap-envelope"> 



<types> 
</types> 

<interface name = " reservationlnterf ace" > 
</interface> 

<binding name="reservationSOAPBinding" 

interface="tns : reservationlnterf ace" 
type="http : //www . w3 . org/ns/wsdl/ soap" 

wsoap:protocol="http: //www. w3.org/2 003/05/soap/bindings /HTTP/ "> 

<operation ref ="tns : opCheckAvailability" 

wsoap:mep="http : //www . w3 . org/ 2 0 03 /0 5/soap/mep/ soap- response" /> 

<f ault ref ="tns : invalidDataFault" 
wsoap: code="soap : Sender "/> 

</binding> 



</description> 



2.1.5.1 Explanation of Example 

xmlns : wsoap= "http://www.w3 . org/ns/wsdl/soap" 

We've added two more namespace declarations. This one is the namespace 
for the SOAP 1 .2 binding extension that is defined in WSDL 2.0 Part 3 [SOAP 
1.2 Part 1: Messaging Framework]. Elements and attributes prefixed with 
wsoap: are constructs defined there. 

xmlns : soap="http: //www. w3 . org/2003/05/ soap-envelope" 

This namespace is defined by the SOAP 1 .2 specification itself. The SOAP 
1 .2 specification defines certain terms within this namespace to 
unambiguously identify particular concepts. Thus, we will use the soap: prefix 
when we need to refer to one of those terms. 

<binding name=" reservationSOAPBinding" 

Bindings are declared directly inside the description element. The name 
attribute defines a name for this binding. Each name must be unique among 
all bindings in this WSDL 2.0 target namespace, and will be used later when 
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we define a service endpoint that references this binding. WSDL 2.0 uses 
separate symbol spaces for interfaces, bindings and services, so interface 
"foo", binding "foo" and service "foo" are all distinct. 

interf ace=" tns : reservationlnterf ace" 

This is the name of the interface whose message format and transmission 
protocols we are specifying. As discussed in 2,5 More on Bindings, a 
reusable binding can be defined by omitting the • • • • attribute. Note 
also the use of the tns : prefix, which refers to the previously defined WSDL 
2.0 target namespace for this WSDL 2.0 document. In this case it may seem 
silly to have to specify the tns : prefix, but in 3.1 Importing WSD L we will 
see how WSDL 2.0's import mechanism can be used to combine 
components that are defined in different WSDL 2.0 target namespaces. 

type="http : //www . w3 . org/ns/wsdl/soap" 

This specifies what kind of concrete message format to use, in this case 
SOAP 1.2. 

wsoap:protocol="http: //www.w3 . org/2003/05/soap/bindings/HTTP/" 

This attribute is specific to WSDL 2.0's SOAP binding extension (thus it uses 
the wsoap: prefix). It specifies the underlying transmission protocol that 
should be used, in this case HTTP. 

<operation ref =" tns : opCheckAvailability " 

This is not defining a new operation; rather, it is referencing the previously 
defined opCheckAvailability operation in order to specify binding details for 
it. This element can be omitted if defaulting rules are instead used to supply 
the necessary information. (See the SOAP binding extension in WSDL 2.0 
Part 2 [WSDL 2.0 Adjuncts] section 4.3 Default Binding Rules .) 

wsoap :mep="http: / /www. w3 . org/2003/05/ soap /mep/soap-response"> 

This attribute is also specific to WSDL 2.0's SOAP binding extension. It 
specifies the SOAP message exchange pattern (MEP) that will be used to 
implement the abstract WSDL 2.0 message exchange pattern ( in-out ) that 
was specified when the opCheckAvailability operation was defined. 
When HTTP is used as the underlying transport protocol (as in this example) 
the wsoap :mep attribute also controls whether GET or POST will be used as 
the underlying HTTP method. In this case, the use of 

wsoap :mep="http : //www . w3 . org/2003/05/soap/mep/soap-response" Causes 

GET to be used by default. See also 2.5.7 HTTP GET Versus POST: Which 
to Use?. 

<fault ref =" tns : invalidDataFault" 

As with a binding operation, this is not declaring a new fault; rather, it is 
referencing a fault (invalidDataFault) that was previously defined in the 
opCheckAvailability interface, in order to specify binding details for it. 

wsoap : code="soap : Sender" /> 

This attribute is also specific to WSDL 2.0's SOAP binding extension. This 
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specifies the SOAP 1 .2 fault code that will cause this fault message to be 
sent. If desired, a list of subcodes can also be specified using the optional 

wsoap: subcodes attribute. 

2.1.6 Defining a Service 

Now that our binding has specified how messages will be transmitted, we are 
ready to specify where the service can be accessed, by use of the service 
element. 

A WSDL 2.0 service specifies a single interface that the service will support, and a 
list of endpoint locations where that service can be accessed. Each endpoint must 
also reference a previously defined binding to indicate what protocols and 
transmission formats are to be used at that endpoint. A service is only permitted to 
have one interface. (See 5.4 Multiple Interfaces for the Same Service for further 
discussion of this limitation.) 
Here is a definition for our GreatH service. 

Example 2-6. GreatH Service Definition 

<?xml version="l . 0" encoding="utf-8 " ?> 
<description 

xmlns="http: //www.w3 . org/ns/wsdl " 

targetNamespace= "http : //greath . example . com/2 004 /wsdl/resSvc" 
xmlns : tns= "http : / /greath . example . com/2004 /wsdl/ resSvc" 
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 
xmlns : wsoap= "http : //www. w3 . org/ns/wsdl /soap" 
xmlns : soap="http: //www. w3 . org/2 0 03/ 05 /soap-envelope "> 



<types> 
</types> 

<interface name = "reservationlnterf ace" > 
</interface> 

<binding name="reservationSOAPBinding" 

interf ace="tns : reservationlnterf ace" 



</binding> 

< service name="reservationService" 

interf ace="tns : reservationInterface"> 

<endpoint name="reservationEndpoint" 

binding="tns : reservationSOAPBinding" 

address ="http: //greath . example . com/2 004 /reservation" /> 

</service> 
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</description> 



2.1.6.1 Explanation of Example 

<service name="reservationService" 

This defines a name for this service, which must be unique among service 
names in the WSDL 2.0 target namespace. The name attribute is required. It 
allows URIs to be created that identify components in WSDL 2.0 description. 
(See WSDL 2.0 Core Language [WSDL 2.0 Core] appendix C URI 
References for WSDL 2.0 constructs.) 

interf ace="tns : reservationInterface"> 

This specifies the name of the previously defined interface that these service 
endpoints will support. 

<endpoint name="reservationEndpoint" 

This defines an endpoint for the service, and a name for this endpoint, which 
must be unique within this service. 

binding=" tns : reservationSOAPBinding" 

This specifies the name of the previously defined binding to be used by this 
endpoint. 

address ="http: //greath . example . com/2004/reservation"/> 

This specifies the physical address at which this service can be accessed 
using the binding specified by the binding attribute. 

That's it! Well, almost. 

2.1.7 Documenting the Service 

As we have seen, a WSDL 2.0 document is inherently only a partial description of a 
service. Although it captures the basic mechanics of interacting with the service - 
the message types, transmission protocols, service location, etc. - in general, 
additional documentation will need to explain other application-level requirements 
for its use. For example, such documentation should explain the purpose and use 
of the service, the meanings of all messages, constraints on their use, and the 
sequence in which operations should be invoked. 

The documentation element allows the WSDL 2.0 author to include some human- 
readable documentation inside a WSDL 2.0 document. It is also a convenient place 
to reference any additional external documentation that a client developer may 
need in order to use the service. It can appear in a number of places in a WSDL 2.0 
document (see 2. 2. 1 WSDL 2.0 inf oset), though in this example we have only 
demonstrated its use at the beginning. 

Example 2-7. Documenting the GreatH Service 

. -.- version="l . 0" encoding="utf-8" ?> f 
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<description 



<documentation> 

This document describes the GreatH Web service. Additional 
application-level requirements for use of this service — 
beyond what WSDL 2.0 is able to describe — are available 
at http : / /greath . example . com/2004/reservation-documentation . html 

</documentation> 

</description> 



2.1.7.1 Explanation of Example 

<documentation> 

This element is optional, but a good idea to include. It can contain arbitrary 
mixed content. 

at http : //greath . example . com/2 004 /reservation-documentation . html 

The most important thing to include is a pointer to any additional 
documentation that a client developer would need in order to use the service. 

This completes our presentation of the GreatH example. In the following sections, 
we will move on to look into more details of various aspects of WSDL 2.0 
specification. 

2.2 WSDL 2.0 Infoset, Schema and Component Model 

In computer science theory, a language consists of a (possibly infinite) set of 
sentences, and each sentence is a finite string of literal symbols or characters. A 
language specification must therefore define the set of sentences in that language, 
and, to be useful, it should also indicate the meaning of each sentence. Indeed, this 
is the purpose of the WSDL 2.0 specification. 

However, instead of defining WSDL 2.0 in terms of literal symbols or characters, to 
avoid dependency on any particular character encoding, WSDL 2.0 is defined in 
terms of the XML Infoset [XML Information Set]. Specifically, a l/l/SDL 2.0 document 
consists of a description element information item (in the XML Infoset) that 
conforms to the WSDL 2.0 specification. In other words, a sentence in the WSDL 
2.0 language is a description element information item that obeys the additional 
constraints spelled out in the WSDL 2.0 specification. 

Since an XML Infoset can be created from more than one physical document, a 
WSDL 2.0 document does not necessarily correspond to a single physical 
document: the word "document" is used figuratively, for convenience. Furthermore, 
since WSDL 2.0 provides import and include mechanisms, a WSDL 2.0 document 
may reference other WSDL 2.0 documents to facilitate convenient organization or 
reuse. In such cases, the meaning of the including or importing document as a 
whole will depend (in part) on the meaning of the included or imported document. 
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The XML Infoset uses terms like "element information item" and "attribute 
information item". Unfortunately, those terms are rather lengthy to repeat often. 
Thus, for convenience, this primer often uses the terms "element" and "attribute" 
instead, as a shorthand. It should be understood, however, that since WSDL 2.0 is 
based on the XML Infoset, we really mean "element information item" and 
"attribute information item", respectively. 



2.2.1 WSDL 2.0 Infoset 



The following diagram gives an overview of the XML Infoset for a WSDL 2.0 
document. 
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Figure 2-1. WSDL 2.0 Infoset Diagram 
2.2.2 WSDL 2.0 Schema 

The WSDL 2.0 specification supplies a normative WSDL 2.0 schema, defined in 
[XML Schema: Structures], which can be used as an aid in validating WSDL 2.0 
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documents. We say "as an aid" here because WSDL 2.0 specification [WSDL 2.0 
Core] often provides further constraints to the WSDL 2.0 schema. In addition to 
being valid with the normative schema, a WSDL 2.0 document must also follow all 
the constraints defined by the WSDL 2.0 specification. 

2. 2. 2. 1 WSDL 2. 0 Element Ordering 

This section gives an example of how WSDL 2.0 specification constrains the 
WSDL 2.0 schema about the ordering of top WSDL 2.0 elements. 
Although the WSDL 2.0 schema does not indicate the required ordering of 
elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 [WSDL 2.0 Core] section 
"XML Representation of Description Component") clearly states a set of 
constraints about how the child elements of the description element should be 
ordered. Thus, the order of the WSDL 2.0 elements matters, even though the 
WSDL 2.0 schema does not capture this constraint. 
The following is a pseudo-content model of description. 



<description> 

documentation />? 

[ <import /> I <include /> ]* 

<types />? 

[ <interface /> i <binding /> I <service /> ]* 
</description> 

In other words, the children elements of the description element should be 
ordered as follows: 

• An optional documentation comes first, if present. 

• then comes zero or more elements from among the following, in any order: 

o include 
O import 

o extensions 

• An optional types follows 

• Zero or more elements from among the following, in any order: 

o interface 
O binding 
o service 

o extensions. 

Note the term "extension" is used above as a convenient way to refer to 
namespace-qualified extension elements. The namespace name of such 
extension elements must not be"http://www.w3.org/ns/wsdl". 

2.2.3 WSDL 2.0 Component Model 
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The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 
2.0 document, using the XML Infoset. However, the WSDL 2.0 language also 
imposes many semantic constraints over and above structural conformance to this 
XML Infoset. In order to precisely describe these constraints, and as an aid in 
precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 
specification defines a component model as an additional layer of abstraction 
above the XML Infoset. Constraints and meaning are defined in terms of this 
component model, and the definition of each component includes a mapping that 
specifies how values in the component model are derived from corresponding 
items in the XML Infoset. The following diagram gives an overview of the WSDL 
2.0 components and their containment hierarchy. 
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Figure 2-2. WSDL 2.0 Components Containment hierarchy 



In general, the WSDL 2.0 component model parallels the structure of the required 
XML Infoset illustrated above. For example, the Description, Interface, Binding, 
Service and Endpoint components correspond to the description, interface, 
binding, service, and endpoint element information items, respectively. Since 
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WSDL 2.0 relies heavily on the component model to convey the meaning of the 
constructs in the WSDL 2.0 language, you can think of the Description component 
as representing the meaning of the description element information item, and 
hence, it represents the meaning of the WSDL 2.0 document as a whole. 
Furthermore, each of these components has properties whose values are (usually) 
derived from the element and attribute information item children of those element 
information items. For example, the Service component corresponds to the 
service element information item, so the Service component has an {endpoints} 
property whose value is a set of Endpoint components corresponding to the 
endpoint element information item children of that service element information 
item. (Whew!) 

2.2.3. 1 WSDL 2.0 Import and Include 

The WSDL 2.0 component model is particularly helpful in defining the meaning of 
import and include elements. The include element allows you to assemble the 
contents of a given WSDL 2.0 namespace from several WSDL 2.0 documents that 
define components for that namespace. The components defined by a given 
WSDL 2.0 document consist of those whose definitions are contained in the 
document and those that are defined by any WSDL 2.0 documents that are 
included in it via the include element. The effect of the include element is 
cumulative so that if document A includes document B and document B includes 
document C, then the components defined by document A consist of those whose 
definitions are contained in documents A, B, and C. 

In contrast, the import element does not define any components. Instead, the 
import element declares that the components whose definitions are contained in a 
WSDL 2.0 document for a given WSDL 2.0 namespace refer to components that 
belong to a different WSDL 2.0 namespace. If a WSDL 2.0 document contains 
definitions of components that refer to other namespaces, then those namespaces 
must be declared via an import element. The import element also has an optional 
location attribute that is a hint to the processor where the definitions of the 
imported namespace can be found. However, the processor may find the 
definitions by other means, for example, by using a catalog. 
After processing any include elements and locating the components that belong 
to any imported namespaces, the WSDL 2.0 component model for a WSDL 2.0 
document will contain a set of components that belong to the document's WSDL 
2.0 namespace and any imported namespaces. These components will refer to 
each other, usually via QName references. A WSDL 2.0 document is invalid if any 
component reference cannot be resolved, whether or not the referenced 
component belongs to the same or a different namespace. 
We will cover a lot more about how to use WSDL 2.0 import and include in 3.1 
Importing WSDL 

2.3 More on Message Types 
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Message types may be defined in various schema languages. In this primer, we 
will only focus on the use of XML Schema [XML Schema: Structures] since it's 
natively supported by WSDL 2.0. Message types defined in other languages may 
be introduced into a WSDL 2.0 description via extensions, see the W3C notes 
[Alternative Schema Languag es Support ] for more details. 
The following is the XML syntax for the wsdi : types element: 



<description> 
< types > 

documentation />* 

[ <xs: import namespace="xs ; anyURI" schemaLocation=" xs : anyURI" ? /> | 
<xs : schema targetNamespace="xs.-any(7KI" /> | 
other extension elements ] * 
</types> 
</description> 

There are two ways to make XML Schema message definitions visible, or in other 
words, available for reference by QName (see WSDL 2.0 Part 1 [WSDL 2.0 Core] 
"QName Resolution") in a WSDL 2.0 document: inlining or importing. Inlining is to 
put the schema definitions directly within an xs : schema element under types. 
Importing is to have the schema defined in a separate document and then bring it 
into the WSDL definition by using xs : import directly under types. 
In the following sections, we will provide examples for the different mechanisms. 

2.3.1 Inlining XML Schema 

We have already seen an example of using inlined schema definitions in section 
2.1.3 Defining Message Types. When XML Schema is inlined directly in a WSDL 
2.0 document, it uses the existing top-level xs: schema element defined by XML 
Schema to do so, as though a schema file had been copied and pasted into the 
types element. The schema components defined in the inlined schema are then 
available to the containing WSDL 2.0 description for reference by QName. For 
instance, in Example 2-1, the input message of the interface operation 
"opCheckAvailability" is defined by the "ghns:checkAvailability" element in the 
inlined schema. 

2.3.2 Importing XML Schema 

XML Schema components can be defined in separate schema files and be made 
available to a WSDL2.0 description by using xs: import directly under types. 
There are many cases where one would prefer having schema definitions in 
separate schema files. One reason is the reusability of the schema definitions. 
Inlined schema definitions are only available to the containing WSDL 2.0 
description. Although WSDL 2.0 provides a wsdi: import mechanism for 
importing other WSDL files, schema definitions inlined in an imported WSDL 
document are NOT automatically made available to the importing WSDL 2.0 
document, even though other WSDL 2.0 components (such as Interfaces, 
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Bindings, etc.) do become available. Therefore, if one wishes to share schema 
definitions across several WSDL 2.0 descriptions, these schema definitions 
should instead be placed in separate XML Schema documents and imported into 
each WSDL 2.0 description using xs: import directly under types. 
Let's see an example. Assuming the message types in Example 2- 3 are defined in 
a separate schema file named 

"http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace 
"http://greath.example.com/2004/schemas/resSvc", the schema definition can then 
be brought into the WSDL 2.0 description using xs : import. Note that only 
components in the imported namespace 

"http://greath.example.com/2004/schemas/resSvc" are available for reference in 
the WSDL 2.0 document. 



Example 2-8. xs: imported Message Definitions that Are Visible to the Containing 
WSDL 2.0 Description 

<?xml version="l . 0" encoding="utf-8" ?> 
description xmlns="http: //www.w3 . org/ns/wsdl" 

targetNamespace= "http : / /greath . example . com/2004/wsdl/resSvc" 
xmlns : tns= "http : //greath . example . com/2004/wsdl/resSvc" 
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 



<types> 

<xs : import namespace="http : //greath . example . com/2 0 04 /schemas/resS 
schemaLocation= "http : //greath . example . com/2 004 /schemas/i 

</types> 



</description> 



It's important to note that xs : import used directly under wsdi : types has been 
given a different visibility than xs : import used inside an inlined schema. An inlined 
schema may use native XML schema xs: import to bring in external schema 
definitions that are in different namespaces; However, though this is the schema 
importing mechanism recommended for WSDL 1.1 in WS-I Basic Profile , 
according to XML Schema specification, such enclosed message definitions are 
only visible to the importing schema (in this case, the inlined schema). They are 
not visible to the containing WSDL 2.0 description. 

If we change Example 2-8 to use XML Schema's native xs : import element in an 
inlined schema, the schema components defined in the namespace 
http://greath.example.com/2004/schemas/resSvc are not available to our example 
WSDL 2.0 definition any more. 

Example 2-9. xs -. imported Message Definitions in Inlined Schema Are Not 
Visible to the Containing WSDL 2.0 Description 

<?xml version="l . 0" encoding="utf-8" ?> j 
<description xmlns="http: //www. w3.org/ns/wsdl" || 
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targetNamespace= "http : //greath . example . com/2004 /wsdl/resSvc" 
xmlns : tns= "http : //greath. example . com/2004/wsdl/resSvc" 
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 



<types> 

<xs : schema targetNamespace="http : //greath . example . com/2004 /schema 
<xs : import namespace="http : //greath . example . com/2004/sche: 
schemaLocation= "http : //greath . example . com/2 004/schemas/r 

</xs : schema> 

</types> 



</description> 

Of course, an inlined XML schema may also use XML Schema's native xs : include 
element to refer to schemas defined in separate files when the included schema 
has no namespace or has the same namespace as the including schema. In this 
case, according to XML Schema, the included schema components become a part 
of the including schema as though they had been copied and pasted into the 
including schema. Hence, the included schema components are also available to 
the containing WSDL 2.0 description for reference by QName. 
The following example has the same effect as Example 2-3: 

xample 2-10. xs: included Message Definitions in Inlined Schema Are Visible to 
<e Containing WSDL 2.0 Description 

<?xml version="l . 0" encoding="utf-8" ?> 

<de script ion xmlns="http : / /www. w3 . org/ns/wsdl " 

targetNamespace= "http: //greath . example . com/2 0 04 /wsdl/resSvc" 
xmlns : tns= "http : / /greath . example . com/2 0 04 /wsdl/resSvc" 
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" 



<types> 

<xs : schema targetNamespace="http : / / greath . example . com/2004 /schema 
<xs: include schemaLocation= "http://greath.example.com/20 
</xs : schema> 

</types> 



</description> 



2.3.3 Summary of Import and Include Mechanisms 



So far we have briefly covered both WSDL import and include and schema import 
and include. The following table summarizes the similarities and differences 
between the WSDL 2.0 and XML Schema include and import mechanisms. We 
will talk a lot more about importing mechanisms in 3,1 Importing WSDL and 3,2 
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impMlng.Sch.emas 

Table 2-1. Summary of Import and Include Mechanisms 



Mechanism 


Object 


Meaning 


Visibility of 

Schema 
Components 


wsdkimport 


WSDL 2.0 
Namespace 


Declare that WSDL 2.0 
components refer to 
WSDL 2.0 components 
from a DIFFERENT 
targetNamespace. 


XML Schema 
Components in the 
imported Description 
component are NOT 
visible to the 
containing 


wsdl:include 


WSDL 2.0 
Document 


Merge Interface, 
Binding and Service 
components from 
another WSDL 2.0 
document that has the 
SAME 

targetNamespace. 


XML Schema 
components in the 
included Description 
component's 
{element 
declarations} and 
{type definitions} 
properties are 
visible to the 
containing 


wsdhtypes/ xs:import 


XML 

Schema 

Namespace 


Declare that XML 
Schema components 
refer to XML Schema 
components from a 
DIFFERENT 
targetNamespace. 


XML Schema 
components in the 
imported 
namespace are 
visible to the 
containing 

description. 


wsdhtypes/ 
xsischema/xsiimport 


XML 

Schema 

Namespace 


Declare that XML 
Schema components 
refer to XML Schema 
components from a 
DIFFERENT 
targetNamespace. 


XML Schema 
components in the 
imported 
namespace are 
NOT visible to the 
containing 

description. 


wsdhtypes/ 
xs:schema/xs:include 


XML 

Schema 

Document 


Merge XML Schema 
components from 
another XML Schema 
document that has the 
SAME or NO 
targetNamespace. 


XML Schema 
components in the 
included document 
are visible to the 
containing 

description. 
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2.4 More on Interfaces 

We previously mentioned that a WSDL 2.0 interface is basically a set of 
operations. However, there are some additional capabilities that we have not yet 
covered. First, let's review the syntax for the interface element. 

2.4.1 Interface Syntax 

Below is the XML syntax summary of the interface element, simplified by omitting 
optional <documentation> elements: 

description targetNamespace= " xs :anyURI" > 



<interface name= " xs :NCName" 

extends=" list of xs:QName"? 
styleDefault="_Zist of xs :anyURI"? > 

<fault name="xs :NCName" 

element="xs :QName"? > 
</fault>* 

<operation name="xs : NCName" 
pattern="xs :anyURI" 
style=" list of xs:anyURI"? 
wsdlx:safe="xs: boolean'"? > 

< input me ssageLabel="xs. 'NCNa/ne"? 

element=" union of xs:QName, xs :Token'"? > 
</input>* 

<output messageLabel="xs:WCWame"? 

eleraent=" union of xs:QName, xs : Token"? > 
</output>* 

<infault ref="xs;QWa7ne" messageLabel="xs : NCName" ? > </infault>* 
<outfault ref="xs:OName" messageLabel = "xs .-NCName" ? > </outfault>* 
</operation>* 
</interf ace>* 



</description> 

The interface element has two optional attributes: styieDefauit and extends. 
The styieDefauit attribute can be used to define a default value for the style 
attributes of all operations under this interface (see WSDL 2.0 Part 1 "styieDefauit 
attribute information item"). The extends attribute is for inheritance, and is 
explained next. 
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2.4.2 Interface Inheritance 

The optional extends attribute allows an interface to extend or inherit from one or 
more other interfaces. In such cases the interface contains the operations of the 
interfaces it extends, along with any operations it defines directly. Two things 
about extending interfaces deserve some attention. 

First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a 
given interface extends must NOT themselves extend that interface either directly 
or indirectly. 

Second, we must explain what happens when operations from two different 
interfaces have the same target namespace and operation name. There are two 
cases: either the component models of the operations are the same, or they are 
different. If the component models are the same (per the component comparison 
algorithm defined in WSDL 2.0 Part 1 [WSDL 2.0 Core] " Equivalence of 
Components ") then they are considered to be the same operation, i.e., they are 
collapsed into a single operation, and the fact that they were included more than 
once is not considered an error. (For operations, component equivalence basically 
means that the two operations have the same set of attributes and descendants.) 
In the second case, if two operations have the same name in the same WSDL 2.0 
target namespace but are not equivalent, then it is an error. For the above reason, 
it is considered good practice to ensure that all operations within the same target 
namespace are named uniquely. 

Finally, since faults can also be defined as children of the interface element (as 
described in the following sections), the same name-collision rules apply to those 
constructs. 

Let's say the GreatH hotel wants to maintain a standard message log operation for 
all received messages. It wants this operation to be reusable across the whole 
reservation system, so each service will send out, for potential use of a logging 
service, the content of each message it receives together with a timestamp and 
the originator of the message. One way to meet such requirement is to define the 
log operation in an interface which can be inherited by other interfaces. Assuming 
a messageLog element is already defined in the ghns namespace with the required 
content, the inheritance use case is illustrated in the following example. As a result 
of the inheritance, the reservationmterface now contains two operations: 

opCheckAvailability and opLogMessage 



Example 2-11. Interface Inheritance 



<description . . . > 

<interface name = "messageLoglnterf ace" > 

<operation name=" opLogMessage" 

pattern="http : //www . w3 . org/ns/wsdl/out-or 
<output messageLabel="out" 

element="ghns :messageLog" /> 

</operation> 
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</interf ace> 

-cinterface name="reservationInterf ace" extends="tns :messageLogIn 

<operation name="opCheckAvailability" 

pattern="http : //www . w3 . org/ns/wsdl/in-out 

style="http : / /www. w3 . org/ns/wsdl/ style /ir 

wsdlx:safe = "true"> 
<input messageLabel="In" 

element="ghns : checkAvailability" /> 
<output messageLabel="Out" 

element="ghns : checkAvailabilityResponse" 
<outfault ref ="tns : invalidDataFault" messageLabel 

</operation> 
</ interf ace> 

</description> 



Now let's have a look at the element children of interface, beginning with fault. 
2.4.3 Interface Faults 

The fault element is used to declare faults that may occur during execution of 
operations of an interface. They are declared directly under interface, and 
referenced from operations where they apply, in order to permit reuse across 
multiple operations. 

Faults are very similar to messages and can be viewed as a special kind of 
message. Both faults and messages may carry a payload that is normally described 
by an element declaration. However, WSDL 2.0 treats faults and messages slightly 
differently. The messages of an operation directly refer to their element declaration, 
however the faults of an operation indirectly refer to their element declaration via a 
fault element that is defined on the interface. 

The reason for defining faults at the interface level is to allow their reuse across 
multiple operations. This design is especially beneficial when bindings are defined, 
since in binding extensions like SOAP there is additional information that is 
associated with faults. In the case of SOAP, faults have codes and subcodes in 
addition to a payload. By defining faults at the interface level, common codes and 
subcodes can be associated with them, thereby ensuring consistency across all 
operations that use the faults 

The fault element has a required name attribute that must be unique within the 
parent interface element, and permits it to be referenced from operation 
declarations. The optional element attribute can be used to indicate a schema for 
the content or payload of the fault message. Its value should be the QName of a 
global element defined in the types section. Please note that when other type 
systems are used to define the schema for a fault message, additional attributes 
may need to be defined via WSDL 2.0's attribute extension mechanism to allow the 
schema to be associated with the fault. 
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2.4.4 Interface Operations 

As shown earlier, the operation element is used to indicate an operation 
supported by the containing interface. It associates message schemas with a 
message exchange pattern (MEP), in order to abstractly describe a simple 
interaction with a Web service. 

2.4.4. 1 Operation Attributes 

An operation has two required attributes and one optional attribute: 

• A required name attribute, as seen already, which must be unique within the 
interface. 

• A required pattern attribute whose value must be an absolute URI that 
identifies the desired MEP for the operation. MEPs are further explained in 
2.4.4.3 Understanding Message Exchange Patterns (MEPs). 

• An optional style attribute whose value is a list of absolute URIs. Each URI 
identifies a certain set of rules that were followed in defining this operation. 
It is an error if a particular style is indicated, but the associated rules are not 
followed. [WSDL 2.0 Adjuncts] defines a set of styles, including 

o RPC Style. The RPC style is selected when the style is assigned the 
value http://www.w3.org/ns/wsdl/rpc. It places restrictions for Remote 
Procedure Call-types of interactions, 
o IRI Style. The IRI style is selected when the style is assigned the 
value http://www.w3.org/ns/wsdl/style/iri. It places restrictions on 
message definitions so they may be serialized into something like 
HTTP URL encoded, 
o The Multipart style. The Multipart style is selected when the style is 
assigned the value http://www.w3.org/ns/wsdl/style/multipart. In the 
HTTP binding, for XForms clients, a message must be defined 
following the Multipart style and serialized as "Multipart/form-data". 
You can find more details of these WSDL 2.0 predefined styles. Section 4,3 
RPC Style provides an example of using the RPC style. [WSDL 2.0 
Adjuncts] provides examples for the IRI style and Multipart style. 

Note that [WSDL 2.0 Adjuncts] provides a predefined extension for indicating 
operation safety. The wsdix: safe global attribute whose value is a boolean can be 
used with an operation to indicate whether the operation is asserted to be 
"safe" (as defined in Section 3.5 of the Web Architecture [Web Architecture]) for 
clients to invoke. In essence, a safe operation is any operation that does not give 
the client any new obligations. For example, an operation that permits the client to 
check prices on products typically would not obligate the client to buy those 
products, and thus would be safe, whereas an operation for purchasing products 
would obligate the client to pay for the products that were ordered, and thus would 
not be safe. 
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An operation should be marked safe (by using the wsdix:safe and by setting its 
value to "true") if it meets the criteria for a safe interaction defined in Section 3.5 of 
the Web Architecture [Web Architecture], because this permits the infrastructure to 
perform efficiency optimizations, such as pre-fetch, re-fetch and caching. 
The default value of this attribute is false. If it is false or is not set, then no 
assertion is made about the safety of the operation; thus the operation may or may 
not be safe. 

2.4.4.2 Operation Message References 

An operation will also have input, output, infauit, and/or outfauit element 
children that specify the ordinary and fault message types to be used by that 
operation. The MEP specified by the pattern attribute determines which of these 
elements should be included, since each MEP has placeholders for the message 
types involved in its pattern. 

Since operations were already discussed in 2.1.4 Defining an Interface, this 
section will merely comment on additional capabilities that were not previously 
explained. 

2.4.4.2.1 The messageLabel Attribute 

The messageLabel attribute of the input and output elements is optional. It is not 
necessary to explicitly set the messageLabel when the MEP in use is one of the 
eight MEPs predefined in WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] and it has only 
one message with a given direction. 

2.4.4.2.2 The element Attribute 

The element attribute of the input and output elements is used to specify the 
message content schema (aka payload schema) when the content model is 
defined using XML Schema. As we have seen already, it can specify the QName 
of an element schema that was defined in the types section. However, 
alternatively it can specify one of the following tokens: 

#any 

The message content is any single element. 

#none 

There is no message content, i.e., the message payload is empty. 

#other 

The message content is described by a non-XML type system. Extension 
attributes specify the type. 

The element attribute is also optional. If it is not specified, then the message 
content is described by a non-XML type system. 
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Note that there are situations that the information conveyed in the element 
attribute is not sufficient for a service implementation to uniquely identify an 
incoming message and dispatch it to an appropriate operation. In such situations, 
additional means may be required to aid identifying an incoming message. See 5.1 
EnabiLn^Ea^yjyjessage Dispatch for more detail. 

2.4.4.2.3 Multiple infault or outfault Elements 

When infauit and/or outfault occur multiple times within an operation, they 
define alternative fault messages. 

2.4.4.3 Understanding Message Exchange Patterns (MEPs) 

WSDL 2.0 message exchange patterns (MEPs) are used to define the sequence 
and cardinality of the abstract messages in an operation. By design, WSDL 2.0 
MEPs are abstract. First of all, they abstract out specific message types. MEPs 
identify placeholders for messages, and placeholders are associated with specific 
message types when an operation is defined, which includes specifying which 
MEP to use for that operation. Secondly, unless explicitly stated otherwise, MEPs 
also abstract out binding-specific information like timing between messages, 
whether the pattern is synchronous or asynchronous, and whether the messages 
are sent over a single or multiple channels. 

It's worth pointing out that WSDL 2.0 MEPs do not exhaustively describe the set of 
messages that may be exchanged between a service and other nodes. By some 
prior agreement, another node and/or the service may send other messages (to 
each other or to other nodes) that are not described by the MEP. For instance, 
even though an MEP may define a single message sent from a service to one 
other node, a service defined by that MEP may multicast that message to other 
nodes. To maximize reuse, WSDL 2.0 message exchange patterns identify a 
minimal contract between other parties and Web Services, and contain only 
information that is relevant to both the Web service and the client that engages 
that service. 

A total of eight MEPs are defined in [WSDL 2.0 Adjuncts]. These MEPs should 
cover the most common use cases, but they are not meant to be an exhaustive list 
of MEPs that can ever be used by operations. More MEPs can be defined for 
particular application needs by interested parties. (See 2.4.4.3 Understanding 
Message Exchange Patterns (MEPs) ) 

For the eight MEPs defined by WSDL 2.0, some of them are variations of others 
based on how faults may be generated. For example, the In-Only pattern 
("http://www.w3.org/ns/wsdl/in-only") consists of exactly one message received by 
a service from some other node. No fault can be generated. As a variation of In- 
Only, Robust In-Only pattern ("http://www.w3.org/ns/wsdl/robust-in-only") also 
consists of exactly one message received by a service, but in this case faults can 
be triggered by the message and must be delivered to the originator of the 
message. If there is no path to this node, the fault must be discarded. For details 
about the common fault generation models used by the eight WSDL 2.0 MEPs, 
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see [ WSDL 2. 0 Ad ju nc ts] . 

Depending on how the first message in the MEP is initiated, the eight WSDL 2.0 
MEPs may be grouped into two groups: in-bound MEPs, for which the service 
receives the first message in the exchange, and out-bound MEPs, for which the 
service sends out the first message in the exchange. (Such grouping is not 
provided in the WSDL 2.0 specification and is presented here only for the purpose 
of easy reference in this primer). 

A frequently asked question about out-bound MEPs is how a service knows where 
to send the message. Services using out-bound MEPs are typically part of large 
scale integration systems that rely on mapping and routing facilities. In such 
systems, out-bound MEPs are useful for specifying the functionality of a service 
abstractly, including its requirements for potential customers, while endpoint 
address information can be provided at deployment or runtime by the underlying 
integration infrastructure. For example, the GreatH hotel reservation system may 
require that every time a customer interacts with the system to check availability, 
data about the custome«mistbe4ogged by a CRM system. At design time, it's 
unknown which particular CRM system would be used together with the 
reservation system. To address this requirement, we may change the 
"reservation Interface" in Example 2-1 to include an out-bound loglnquiry operation. 
This loginquiry operation advertises to potential service clients that customer 
data will be made available by the reservation service at run time. When the 
reservation service is deployed to GreatH's IT landscape, appropriate 
configuration time and run time infrastructure will help determine which CRM 
system will get the customer data and log it appropriately. It's worth noting that in 
addition to being used by a CRM system for customer management purpose, the 
same data may also be used by a system performance analysis tool for different 
purpose. Providing an out-bound operation in the reservation service enables 
loose coupling and so improves the overall GreatH IT landscape's flexibility and 
scalability. 



Example 2-12. Use of outbound MEPs 




<description ...> 




<interface name="reservationInterf ace"> 




<operation name="opCheckAvailability" . 


. . > 



<operation name="opLogInquiry" 

pattern="http : //www . w3 . org/ns/wsdl/out-or 
<output messageLabel="Out" element="ghns : customei 

</operation> 



</interf ace> 
</description> 



Although the eight MEPs defined in WSDL 2.0 Part 2 \WSDL 2.0 A djun cts] are 
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intended to cover most use cases, WSDL 2.0 has designed this set to be 
extensible. This is why MEPs are identified by URIs rather than a fixed set of 
tokens. 

For more about defining new MEPs, see 4.2 Defining New MEPs, 

2.5 More on Bindings 

Bindings are used to supply protocol and encoding details that specify how 
messages are to be sent or received. Each binding element uses a particular 
binding extension to specify such information. WSDL 2.0 Part 2 [WSDL 2.0 
Adjuncts] defines several binding extensions that are typically used. However, 
binding extensions that are not defined in WSDL 2.0 Part 2 can also be used, 
provided that client and service toolkits support them. 

Binding information must be supplied for every operation in the interface that is 
used in an endpoint. However, if the desired binding extension provides suitable 
defaulting rules, then the information will only need to be explicitly supplied at the 
interface level, and the defaulting rules will implicitly propagate the information to 
the operations of the interface. For example, see the Default B i nding Rules of 
SOAP binding extension in WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts]. 

2.5.1 Syntax Summary for Bindings 

Since bindings are specified using extensions to the WSDL 2.0 language (i.e., 
binding extensions are not in the WSDL 2.0 namespace), the XML for expressing 
a binding will consist of a mixture of elements and attributes from WSDL 2.0 
namespace and from the binding extension's namespace, using WSDL 2.0's open 
content model. 

Here is a syntax summary for binding, simplified by omitting optional 
documentation elements. Bear in mind that this syntax summary only shows the 
elements and attributes defined within the WSDL 2.0 namespace. When an actual 
binding is defined, elements and attributes from the namespace of the desired 
binding extension will also be intermingled as required by that particular binding 
extension. 



<description targetNamespace="xs :anyURI" > 

<binding name="xs : NCName" interf ace="xs ; QName" ? > 

<fault ref="xs; QName" > </fault>* 

<operation ref ="xs : QName" > 

<input messageLabel="xs :NCName"? > </input>* 
<output messageLabel="xs .-NCName"? > </output>* 

<infault ref="xs: QName" messageLabel="xs ; NCName"? > </infault>* 
-Coutfault ref = "xs : r QName" messageLabel = "xs :NCName" ? > </outfault>* 
</operation>* 

</binding>* 
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</description> 

The binding syntax parallels the syntax of interface: each interface construct has 
a binding counterpart. Despite this syntactic similarity, they are indeed different 
constructs, since they are in different symbol spaces and are designed for different 
purposes. 

2.5.2 Reusable Bindings 

A binding can either be reusable (applicable to any interface) or non-reusable 
(specified for a particular interface). Non-reusable bindings may be specified at the 
granularity of the interface (assuming the binding extension provides suitable 
defaulting rules), or on a per-operation basis if needed. A non-reusable binding 
was demonstrated in 2.1.5 Defining a Binding. 

To define a reusable binding, the binding element simply omits the interface 
attribute and omits specifying any operation-specific and fault-specific binding 
details. Endpoints can later refer to a reusable binding in the same manner as for 
a non-reusable binding. Thus, a reusable binding becomes associated with a 
particular interface when it is referenced from an endpoint, because an endpoint is 
part of a service, and the service specifies a particular interface that it implements. 
Since a reusable binding does not specify an interface, reusable bindings cannot 
specify operation-specific details. Therefore, reusable bindings can only be 
defined using binding extensions that have suitable defaulting rules, such that the 
binding information only needs to be explicitly supplied at the interface level. 

2.5.3 Binding Faults 

A binding fault associates a concrete message format with an abstract fault of an 
interface. It describes how faults that occur within a message exchange of an 
operation will be formatted, since the fault does not occur by itself. Rather, a fault 
occurs as part of a message exchange specified by an interface operation and its 
binding counterpart, the binding operation. 

A binding fault has one required ref attribute which is a reference, by QName, to 
an interface fault. It identifies the abstract interface fault for which binding 
information is being specified. Be aware that the value of ref attribute of all the 
faults under a binding must be unique. That is, one cannot define multiple 
bindings for the same interface fault within a given binding. 

2.5.4 Binding Operations 

A binding operation describes a concrete binding of an interface operation to a 
concrete message format. An interface operation is uniquely identified by the 
WSDL 2.0 target namespace of the interface and the name of the operation within 
that interface, via the required ref attribute of binding operation. As with faults, for 
each operation within a binding, the value of the ref attribute must be unique. 
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2.5.5 The SOAP Binding Extension 

The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 [WSDL 2.0 
Adjuncts]) was primarily designed to support the features of SOAP 1 .2 [SOAPt2 
Part 1: Messa ging Fr amew ork]. However, for backwards compatibility, it also 
provides some support for SOAP 1.1 [SOAP 1.1]. 

An example using the WSDL 2.0 SOAP binding extension was already presented 
in 2.1.5 Defining a Binding, but some additional points are worth mentioning: 

• Because the same binding extension is used for both SOAP 1 .2 and SOAP 
1.1, a wsoap: version attribute is provided to allow you to indicate which 
version of SOAP you want. If this attribute is not specified, it defaults to 
SOAP 1.2. 

• The WSDL 2.0 SOAP binding extension defines a set of default rules, so that 
bindings can be specified at the interface level or at the operation level (or 
both), with the operation level taking precedence. However, it does not 
define default binding rules for faults. Thus, if a given interface defines any 
faults, then corresponding binding information must be explicitly provided for 
each such fault. 

• If HTTP is used as the underlying protocol, then the binding can (and should) 
control whether each operation will use HTTP GET or POST. (See 2.5.7 
HTTP GET Versus POST: Which to Use? ) 

Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and 
a SOAP 1.1 binding. 



Example 2-13. SOAP 1.2 and SOAP 1.1 Bindings 

<?xml version="l . 0" encoding="utf -8 " ?> 
<description 

xmlns="http : //www . w3 . org/ns/wsdl" 

targetNamespace="http : //greath . example . com/2 0 04 /wsdl/resSvc" 

xmlns : tns="http : //greath . example . com/2 0 04 /wsdl/resSvc" 

xmlns :ghns="http: //greath. example . com/2 004 /schemas/resSvc" 

xmlns : wsoap="http : //www . w3 . org/ns/wsdl /soap" 

xmlns : soap="http: //www. w3 . org/2 003/ 05/ soap-envelope" 

xmlns : soapll="http : //schemas . xmlsoap . org/soap/envelope/"> 



<!— SOAP 1.2 Binding — > 

<binding name="reservationSOAPBinding" 

interf ace="tns : reservationlnterf ace" 

type="http: //www. w3 . org/ns/wsdl/soap" 

wsoap :protocol="http: //www. w3. org/2 003/ 05/soap/bindings/HTTP/"> 

<operation ref ="tns : opCheckAvailability" 

wsoap :mep="http : //www. w3 .org/2003/ 05/soap/mep/request-response"/> 

<f ault ref="tns : invalidDataFault" 
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wsoap : code=" soap: Sender" /> 

</binding> 

<! — SOAP 1.1 Binding — > 

<binding name="reservationSOAPHBinding" 

interf ace="tns : reservationlnterf ace" 

type="http: //www.w3 . org/ns/wsdl/soap" 

wsoap:version="l . 1" 

wsoap :protocol="http: //www. w3.org/2 00 6/0 1/soapll /bindings/HTTP/ "> 

<operation ref="tns : opCheckAvailability" /> 

<f ault ref ="tns : invalidDataFault" 
wsoap : code="soapll : Client"/> 

</binding> 



<service name=" reservationService" 

interface="tns: reservationlnterf ace" > 

<!-- SOAP 1.2 End Point — > 
<endpoint name="reservationEndpoint" 
binding="tns : reservationSOAPBinding" 

address="http: / /greath . example . com/ 2 0 04 /reservation" /> 

<!-- SOAP 1.1 End Point — > 
<endpoint name="reservationEndpoint2" 
binding="tns : reservationSOAPl 1 Binding" 

address="http : //greath. example . com/2 004/ reservation" /> 

</service> 
</description> 



2.5.5.1 Explanation of Example 

Most lines in this example is the same as previously explained in 2.1.5 Defining a 
Bi nding , so we'll only point out lines that are demonstrating something new for 
SOAP 1.1 binding. 

<description . . . xmlns : soapll="http : //schemas . xmlsoap. org/soap/envelope/"> 

This is the namespace for terms defined within the SOAP 1.1 specification 

[SOAP 1.1). 

<binding. . .wsoap :version="l . 1" 

This line indicates that this binding uses SOAP 1.1 [WSDL 2.0 SOAP 1.1 
Binding], rather than SOAP 1.2. 

wsoap : pro tocol="http : //www. w3 .org/2006/01 /soapll /bindings/HTTP/ "> 

This line specifies that HTTP should be used as the underlying transmission 
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protocol. See also 2,5 .7 H TTP GET Vers us POST: Which to Use?. 

<operation ref=" tns : opCheckAvailability"/> 

Note that wsoap:mep is not applicable to SOAP 1.1 binding. 
<fault. . . wsoap: code="soapll :Client"/> 

This line specifies the SOAP 1.1 fault code that will be used in transmitting 
invalidDataFault. 

2.5.6 The HTTP Binding Extension 

In addition to the WSDL 2.0 SOAP binding extension described above, WSDL 2.0 
Part 2 [WSDL 2.0 Adjuncts] defines a binding extension for HTTP 1.1 [IETF RFC 
2616] and HTTPS [IETF RFC 2818], so that these protocols can be used natively 
to send and receive messages, without first encoding them in SOAP. 
The HTTP binding extension provides many features to control: 

. Which HTTP operation will be used. (GET, PUT, POST, DELETE, and other 
HTTP operations are supported.) 

• Input, output and fault serialization 

• Transfer codings 

• Authentication requirements 

• Cookies 

• HTTP over TLS (https) 

As with the WSDL 2.0 SOAP binding extension, the HTTP binding extension also 
provides defaulting rules to permit binding information to be specified at the 
interface level and used by default for each operation in the affected interface, 
however, defaulting rules are not provided for binding faults. 
Here is an example of using the HTTP binding extension to check hotel room 
availability at GreatH. 

|Examp/e 2-U~HTTP Binding Extension 

<?xml version="l . 0" encoding="utf-8" ?> 

<de script ion xmlns="http : //www . w3 . org/ns/wsdl" 

xmlns :whttp="http: //www.w3 . org/ns/wsdl/http" > 



<binding name="reservationHTTPBinding" 

interf ace="tns : reservationlnterf ace" 
type="http: //www. w3.org/ns/wsdl/http" 
whttp:methodDefault="GET"> 

<operation ref ="tns : opCheckAvailability" 
whttp: location=" { checklnDate } " /> 

</binding> 
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< service name="reservationService" 

interf ace="tns : reservationlnterf ace"> 

<! — HTTP 1.1 GET End Point — > 
<endpoint name="reservationEndpoint" 
binding="tns : reservationHTTPBinding" 

address="http : / /greath . example . com/2004/checkAvailability/"/> 
</ service> 
</ description> 



2.5.6.1 Explanation of Example 

Most of this example is the same as previously explained in 2.1.5 Defining a 
Binding , so we'll only point out lines that are demonstrating something new for 
HTTP binding extension. 

<description. . .xmlns :whttp="http: //www. w3 . org/ns/wsdl/http" > 

This defines the namespace prefix for elements and attributes defined by the 
WSDL 2.0 HTTP binding extension. 

<binding. . . type="http: //www. w3.org/ns/wsdl/http" 

This declares the binding as being an HTTP binding. 

wh ttp : me thodDe f aul t= " GET " > 

The default method for operations in this interface will be HTTP GET. 

whttp:location=" {checklnDate} " > 

The whttp: location attribute specifies a pattern for serializing input message 
instance data into the path component of the request URI. The default binding 
rules for HTTP specify that the default input serialization for GET is 
appiication/x-www-f orm-uriencoded. Curly braces are used to specify the 
name of a schema type in the input message schema, which determines what 
input instance data will be inserted into the path component of the request 
URI. The curly brace-enclosed name will be replaced with instance data in 
constructing the path component. Remaining input instance data (not 
specified by whttp: location) will either be serialized into the query string 
portion of the URI or into the message body, as follows: if a 7" is appended to 
a curly brace-enclosed type name, then any remaining input message 
instance data will be serialized into the message body. Otherwise it will be 
serialized into query parameters. 

Thus, in this example, each of the elements in the tcheckAvaiiabiiity type 
will be serialized into the query parameters. A sample resulting URI would 
therefore be http://greath.exampie.com/2004/checkAvaiiabiiity/5-5-5? 

checkOutDate=6-6-5&roomType=f 00. 
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Here is an alternate example that appends 7" to the type name in order to serialize 
the remaining instance data into the message body: 



Examp/e 2-15. Serializing a Subset of Types in the Path 

<operation ref ="tns : opCheckAvailability" 

whttp : location="bycheckInDate/ { checklnDate/ } " > 



This would instead serialize to a request URI such as: 

http: //greath. example . com/2004/checkAvailability/bycheckInDate/5-5-5. The 

rest of the message content would go to the HTTP message body. 
2.5.7 HTTP GET Versus POST: Which to Use? 

When a binding using HTTP is specified for an operation, the WSDL 2.0 author 
must decide which HTTP method is appropriate to use -- usually a choice between 
GET and POST. In the context of the Web as a whole (rather than specifically 
Web services), the W3C Technical Architecture Group (TAG) has addressed the 
question of when it is appropriate to use GET, versus when to use POST, in a 
finding entitled URIs, Addressability, and the use of HTTP GET and POST([W3C 
TAG Finding: Use of HTTP GET]). From the abstract: 

". . . designers should adopt [GET] for safe operations such as simple queries. 
POST is appropriate for other types of applications where a user request has the 
potential to change the state of the resource (or of related resources). The finding 
explains how to choose between HTTP GET and POST for an application taking 
into account architectural, security, and practical considerations." 
Recall that the concept of a safe operation was discussed in 2.4.4.1 Operation 
Attributes. (Briefly, a safe operation is one that does not cause the invoker to 
incur new obligations.) Although the wsdix : safe attribute of an interface operation 
indicates that the abstract operation is safe, it does not automatically cause GET 
to be used at the HTTP level when the binding is specified. The choice of GET or 
POST is determined at the binding level: 

• If the WSDL 2.0 SOAP binding extension is used (2.5.5 The SOAP Binding 
Extension), with HTTP as the underlying transport protocol, then GET may 
be specified by setting: 

wsoap:protocol="http: //www. w3.org/2003/05/soap/bindings/HTTP/" 

on the binding element (to indicate the use of HTTP as the underlying 
protocol); and 

wsoap:mep="http: //www. w3 . org/2003/05/ soap /mep/ soap-response/" 

on the binding operation element, which causes GET to be used by 
default. 

• If the WSDL 2.0 HTTP binding extension is used directly (2.5.6 The HTTP 
Binding Extension), GET may be specified by setting either: 
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whttp :methodDef ault="GET" 

on the binding element; or 

whttp :method="GET" 

on the binding operation element, which overrides 

whttp rmethodDe fault if set on the binding element; or 

wsdlx: safe="true" 

on the bound interface operation . When the above two items are 
not explicitly set, and when the bound interface operation is marked 
safe, the HTTP Binding will by default set the method to GET. 

For example, in the GreatH interface definition shown in Ex ample 2-4 , the 
wsdlx:safe attribute is set to "true". The HTTP binding definition in Example 2-14 
may take advantage of that and be simplified as below and still have the http 
method set to GET by default: 



\Example 2-16. Safety and HTTP Binding 


<?xml version="l . 0" encoding="utf-8" ?> 






<binding name="reservationHTTPBinding" 






interf ace="tns : reservationlnterf ace" 






type="http: //www. w3.org/ns/wsdl/http" > 






<operation ref ="tns : opCheckAvailability" 






whttp : 1 oca tion=" { checklnDate } "/> 






</binding> 







3. Advanced Topics I: Importing Mechanisms 
3.1 Importing WSDL 

In some circumstances WSDL authors may want to split up a Web service 
description into two or more documents. For example, if a description is getting 
long or is being developed by several authors, then it is convenient to divide it into 
several parts. Another very important case is when you expect parts of the 
description to be reused in several contexts. Clearly it is undesirable to cut and 
paste sections of one document into another, since that is error prone and leads to 
maintenance problems. More importantly, you may need to reuse components that 
belong to a wsdhtargetNamespace that is different than that of the document you 
are writing, in which case the rules of WSDL 2.0 prevent you from simply cutting 
and pasting them into your document. 

To solve these problems, WSDL 2.0 provides two mechanisms for modularizing 



http://www.w3.org/TR/2007/WD-wsdl20-primer-20070326/ 



5/8/2007 



Web Services Description Language (WSDL) Version 2.0 Part 0: Primer 



Page 44 of 85 



Web service description documents: import and include. This section discusses 
the import mechanism and describes some typical cases where it may be used. 
The import mechanism lets one refer to the definitions of Web service 
components that belong to other namespaces. To illustrate this, consider the 
GreatH hotel reservation service. Suppose that the reservation service uses a 
standard credit card validation service that is provided by a financial services 
company. Furthermore, suppose that companies in the financial services industry 
decided that it would be useful to report errors in credit card validation using a 
common set of faults, and have defined these faults in the following Web service 
description: 

Example 3-1. Standard Credit Card Validation Faults (credit-card-faults.wsdl) 

<?xml version="l . 0" encoding="utf-8" ?> 

description xmlns="http: //www.w3 . org/ns/wsdl " 

targetNamespace="http: //finance .example . com/CreditCards/wsdl" 
xmlns : tns="http: / /finance . example . com/CreditCards/wsdl" 
xmlns : cc="http : / / finance . example . com/ CreditCards/xsd"> 

<documentation> 

This document describes standard faults for use 
by Web services that process credit cards. 
</documentation> 

<types> 

<xs : import xmlns : xs="http : //www . w3 . org/2 001 /XMLSchema" 

namespace="http : //finance . example . com/CreditCardFaults/xsd" 
schemaLocation="credit-card-faults . xsd" /> 

</types> 

< inter face name="creditCardFaults"> 

<f ault name=" cancel ledCreditCard" element="cc : CancelledCreditCarc 
<documentation>Thrown when the credit card has been cancellec 
</fault> 

<f ault name="expiredCreditCard" element="cc : ExpiredCreditCard"> 

<documentation>Thrown when the credit card has expired . </doci 
</fault> 

<f ault name="invalidCreditCardNumber " element="cc : InvalidCreditCs 
<documentation>Thrown when the credit card number is invalid. 
This fault will occur if the wrong credit card type is sj 
</documentation> 
</fault> 

<f ault name="invalidExpirationDate" element="cc : InvalidExpiratior 
<documentation>Thrown when the expiration date is invalid. </c 
</fault> 

</interface> 

</description> 
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This example defines an interface, creditcardFauits, that contains four faults, 

cancelledCreditCard, expiredCreditCard, invalidCreditCardNumber, and 

invaiidExpirationDate. These components belong to the namespace 

http : //finance . example . com/CreditCards/wsdl. 

Because these faults are defined in a different wsdl:targetNamespace than the 
one used by the GreatH Web service description, import must be used to make 
them available within the GreatH Web service description, as shown in the 
following example: 

Example 3-2. Using the Standard Credit Card Validation Faults (use-credit-card- 
faults.wsdl) 



<?xml version="l . 0"?> 
<description 

targetNamespace="http : //greath . example . com/2004/wsdl/resSvc" 
xmlns : ghns="http : //greath . example . com/2004 /schemas/resSvc" 
xmlns : cc="http : //finance . example . com/CreditCards/wsdl" 
xmlns="http : / /www . w3 . org/ns/wsdl " 
xmlns :xs="http: //www. w3.org/2 001 /XMLSchema"> 

<documentation> 

Description: The definition of the reservation Web servic 
GreatH hotel. Author: Joe Somebody Date: 05/17/2004 

</documentation> 

< import name space= "http : //finance . example . com/CreditCards/wsdl " 
1 oca tion=" credit-card- faults . wsdl"/> 

<interf ace name=" reservation" extends="cc : creditCardFaults"> 

<operation name="makeReservation" 

pattern="http: //www.w3 . org/ns/wsdl /in-out"> 

<input messageLabel="In" element="ghns :makeReser\ 

<output messageLabel="Out" 

element="ghns :makeReservationResponse" /; 

<outfault ref ="invalidDataFault" messageLabel="Oi 

<outfault ref="cc: cancelledCreditCard" messageLak 

<outfault ref="cc : expiredCreditCard" messageLabe] 

<outfault ref ="cc : invalidCreditCardNumber" messac 

<outfault ref="cc : invaiidExpirationDate" messagel 
</operation> 

</description> 



The hotel reservation service declares that it is using components from another 
namespace via the im P ort> element. The import element has a required 
namespace attribute that specifies the other namespace, and an optional location 
attribute that gives the processor a hint where to find the description of the other 
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namespace. The reservation interface extends the creditcardFauit interface 
from the other namespace in order to make the faults available in the reservation 
interface. Finally, the makeReservation operation refers to the standard faults in its 
outfauit elements. 

Another typical situation for using imports is to define a standard interface that is to 
be implemented by many services. For example, suppose the hotel industry 
decided that it was useful to have a standard interface for making reservations. 
This interface would belong to some industry association namespace, e.g. 

http://hotels.example.com/reservations/wsdl. Each hotel that implemented the 

standard reservation service would define a service in its own namespace, e.g. 

http://greath.exampie.com/2004/wsdi/ressvc. The description of each service 

WOUld import the http://hotels.example.com/reservations/wsdl namespace and 

refer to the standard reservation interface in it. 

3.2 Importing Schemas 

WSDL 2.0 documents may contain one or more XML schemas defined within the 
wsdi : types element. This section illustrates the correct way to refer to these 
schemas, both from within the same document and from other documents. 

3.2.1 Schemas in Imported Documents 

In this example, we consider some GreatH Hotel Web services that retrieve and 
update reservation details. The retrieval Web service is defined in the 
retrieveDetaiis . wsdi WSDL 2.0 document, along with a schema for the 
message format. The updating Web service is defined in the updateDetaiis.wsdi 
WSDL 2.0 document which imports the first document and refers to both WSDL 
2.0 and schema definitions contained in the imported document. 
Example 3-3 shows the definition of the retrieval Web service in the 

http://greath.example.com/2 0 04/services/retrieveDetails namespace. This 

WSDL 2.0 document also contains an inline schema that describes the reservation 

detail in the http: //greath .example . com/2 0 04 /schemas /reservationDetails 

namespace. This schema is visible to the retrieveDetaiismterface interface 
definition which refers to it in the retrieve operation's output message. 

Example 3-3. The Retrieve Reservation Details Web Service: retrieveDetails.wsdl 

<?xml version="l. 

description xmlns="http : //www . w3 . org/ns/wsdl " 

targe tName spa ce=" http : //greath . example . com/2 004 /services/ retrieve 
xmlns : tns="http : //greath. example . com/2 004 /services/ ret rieveDetai] 
xmlns : wde tail s= "http: //greath . example . com/2004 /schemas /reservatic 
xmlns : xs="http : //www . w3 . org/2 001 /XMLSchema"> 

<documentation> 

This document describes the GreatH Retrieve Reservation E 

Web service. 
</documentation> 
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<xs : schema xmlns="http: //www.w3 . org/2001/XMLSchema" 

targe tNamespace="http : //greath . example . com/20 04 /s 

<xs :element name="reservationDetails"> 
<xs : complexType> 

<xs : sequence> 

type="string" /> 
<xs: element name="checkln 
<xs: element name="checkOu 
<xs:element name="roomTyp 
<xs: element name="smoking 
</xs : sequence> 
</xs : complexType> 
</xs:element> 
</xs : schema> 

</types> 

<interface name=" re trieveDe tails Interface" > 

<operation name="retrieve" 

pattern="http: //www.w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" element="#none" /> 
<output messageLabel="Out" 

element="wdetails : reservationDetails" /> 

</operation> 
</interf ace> 
</description> 



Example 3-4 shows the definition of the updating Web service in the 

http: //greath. example . com/2 004 /services/updateDetails namespace. The 
updateDetailsInterface interface extends the retrieveDetailsInterface 

interface. However, the retrieveDetaiisinterf ace belongs to the 

http : //greath . example . com/2 004/ services /retrieveDetails namespace, SO 
updateDetails.wsdl must import retrieveDetails . wsdl to make that namespace 

visible. 

The updateDetailsInterface interface alSO USeS the reservationDetails element 

definition that is contained in the inline schema of the imported 
retrieveDetails. wsdi document. However, this schema is not automatically visible 
within the updateDetails.wsdl document. To make it visible, the 
updateDetaiis . wsdi document must import the namespace of the inline schema 
within the types element using the XML schema import element. 
In this example, the schemaLocation attribute of the import element has been 
omitted. The schemaLocation attribute is a hint to the WSDL 2.0 processor that tells 
it where to look for the imported schema namespace. However, the WSDL 2.0 
processor has already processed the retrieveDetails. wsdi document which 
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contains the imported namespace in an inline schema so it should not need any 
hints. However, this behavior depends on the implementation of the processor and 
so cannot be relied on. 

Although the WSDL 2.0 document may validly omit the schemaLocation attribute, it 
is a best practice to either provide a reliable value for it or move the inline schema 
into a separate document, say reservationDetaiis.xsd, and directly import it in 

the types element Of both retrieveDetails.wsdl and updateDetails.wsdl. In 

general, schemas that are expected to be referenced from more than one WSDL 
2.0 document should be defined in a separate schema document rather than be 
inlined. 



Example 3-4. The Update Reservation Details Web Service: updateDetails.wsdl 



<?xml version="l . 0" encoding="utf-8 " ?> 

description xmlns="http : //www . w3 . org/ns/wsdl " 

targe tNamespace="http: //greath . example . com/2 004 /services /updateDe 
xmlns : tns="http : //greath . example . com/2004/services/updateetails" 
xmlns : retrieve="http : //greath . example . com/2 0 04 / services /retrieve! 
xmlns : detail s = "http : //greath . example . com/2 0 04/ schema s/reservatior 
xmlns :xs = "http: / /www . w3 . org/2 001 /XMLSchema " > 

<documentation> 

This document describes the GreatH Update Reservation Det 

Web service. 
</documentation> 

<import 

namespace="http : //greath . example . com/ 2 0 04 /services /re trie 
location="retrieveDetails . wsdl" /> 

<types> 

<xs: import 

namespace="http : //greath . example . com/ 2 004 /schemas 

</types> 

< inter face name="updateDetai Is Interface" 

extends=" retrieve : re t r ieveDe tails Inter f ace" > 

<operation name="update" 

pattern="http : //www . w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" 

element="details : reservationDetails" /> 
<output messageLabel="Out" 

element="details : reservationDetails" /> 

</operation> 
</interf ace> 
</description> 



3.2.2 Multiple Inline Schemas in One Document 
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A WSDL 2.0 document may define multiple inline schemas in its types element. 
The two or more schemas may have the same target namespace provided that 
they do not define the same elements or types. It is an error to define the same 
element or type more than once, even if the definitions are identical. 
Each namespace of an inline schema becomes visible to the Web service 
definitions. However, the namespaces are not automatically visible to the other 
inline schemas. Each inline schema must explicitly import any other namespace it 
references. The schemaLocation attribute is not required in this case since the 
WSDL 2.0 processor knows the location of each schema by virtue of having 
processed the enclosing WSDL 2.0 document. 

To illustrate this, consider Example 3-5 which contains two inline schemas. The 

http: //greath. example . com/2004/schemas/reservationltems namespace 

contains some elements for items that appear in the reservation details. The 

http: //greath. example . com/2004 /schemas /reservationDetai Is namespace 

contains the reservationDetaiis element which refers to the item elements. The 

Schema for the http: //greath .example . com/2 004 /schemas /reservationDetaiis 

namespace contains an import element that imports the 

http: //greath. example . com/2 004 /schemas /reservationl terns namespace. No 

schemaLocation attribute is required for this import since the schema is defined 
inline in the importing document. 

Example 3-5. Multiple Inline Schemas: retrieveltems.wsdl 

<?xml versicn="l . 0" encoding="utf-8" ?> 

<de script ion xmlns="http: //www.w3 .org/ns/wsdl" 

targetNamespace= "http: //greath. example . com/ 2 00 4 /services /retrieve 
xmlns : tns="http : //greath . example . com/ 2 0 04 / services /retrieveDetai] 
xmlns :wdetails= "http: //greath. example . com/ 2 004 /schemas /reservatic 
xmlns :xs="http: //www. w3.org/2 00 1 /XMLSchema"> 

<documentation> 

This document describes the GreatH Retrieve Reservation t 

Web service. 
</documentation> 

<types> 

<xs : schema targetNamespace="http : //greath . example . com/2 0C 

<xs:element name="conf irmationNumber" type="strir 
<xs: element name="checkInDate" type="date" /> 
<xs:element name="checkOutDate" type="date" /> 
<xs:element name="roomType" type="string" /> 
<xs:element name="smoking" type="boolean" /> 

</xs : schema> 

<xs: schema targetNamespace="http : //greath . example . com/20C 
xmlns : items="http : //greath . example . com/20 04 /schen 

I <xs: import 
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namespace="http : //greath . example . com/2 004 

<xs :element name="reservationDetails"> 
<xs : complexType> 

<xs : sequence> 

<xs: element ref 
<xs: element ref 
<xs: element ref 
<xs: element ref 
<xs: element ref 
</xs : sequence> 
</xs : complexType> 
</xs : element> 
</xs : schema> 

</types> 

<interface name="retrieveDetailsInterface"> 

<operation name="retrieve" 

pattern="http: //www. w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" element="#none" /> 
<output messageLabel="Out" 

element="wdetails : reservationDetails" /> 

</interf ace> 
</description> 



3.2.3 The schemaLocation Attribute 

In the preceding examples, schemas were defined inline in WSDL 2.0 documents. 
This section discusses the correct way to specify a schemaLocation attribute on a 
schema import element to provide a processor with a hint for locating these 
schemas. 

Example 3-4 shows how one WSDL 2.0 document imports a schema defined in 
another, i.e. Example 3-3. Similarly, Example 3-5 shows how one schema in a 
WSDL 2.0 document imports another schema defined in the same document. In 
both of these examples, the schemaLocation attribute was omitted since the WSDL 
2.0 processor was assumed to know how to locate the imported schemas because 
they were part of the WSDL 2.0 documents being processed. The schemaLocation 
attribute can be used to give the processor a URI reference that explicitly locates 
the schemas. A URI reference is a URI plus an optional fragment identifier that 
indicates part of the resource. For schemas, the fragment should identify the schema 
element. The simplest way to accomplish this is to use the id attribute, however 
XPointer (see [XP o i nter Framework] ) can also be used. 

3.2.3. 1 Using the id Attribute to Identify Inline Schemas 



="items : co 
="items : ch 
=" items : ch 
="items : ro 
="items : sm 
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Example 3-6 shows the use of the id attribute. Both of the inline schemas have id 
attributes. The id of the 

http://greath.example.com/2004/schemas/reservationltems Schema is items 
and the id Of the http: //greath. example.com/2004/schemas/reservationDetails 
schema is details. The import element in the 

http://greath.example.com/2004/schemas/reservationDetails Schema USeS the 
id Of the http://greath.example.com/2004/schemas/reservationltems Schema in 
the schemaLocation attribute, i.e. #items. 

Example 3-6. Using Ids in Inline Schemas: schemalds.wsdl 

<?xml version="l . 0" encoding="utf-8 " ?> 

<description xmlns="http: //www. w3 . org/ns/wsdl " 

targe tName spa ce=" http: //greath . example . com/ 2 004 /services /retrieve 
xmlns : tns="http : //greath . example . com/ 20 04 / services /retrieveDetai] 
xmlns : wdetails="http : //greath . example . com/2 0 04 /schemas/reservatic 
xmlns : xs="http : / /www . w3 . org/2 0 01 /XMLSchema"> 

<documentation> 

This document describes the GreatH Retrieve Reservation I 

Web service. 
</ documentation> 

<types> 

<xs: schema id=" items" 

targe tName space= "http : / /greath. example . com/ 20 04 / s. 

<xs:element name="conf irmationNumber" type="strir 
<xs:element name="checkInDate" type="date" /> 
<xs:element name="check0utDate" type="date" /> 
<xs: element name="roomType" type="string" /> 
<xs:element name="smoking" type="boolean" /> 



</xs : schema> 



<xs: schema id="details" 

targetNamespace="http : / /greath . example . com/2004 /e 
xmlns : items="http : / /greath . example . com/2 004 /schen 

<xs : import 

namespace="http : / /greath . example . com/2 0 0'; 
schemaLocation=" litems" /> 



<xs :element name="reservationDetails"> 
<xs : complexType> 

<xs : sequence> 

<xs: element ref ="items : cc 
<xs: element ref ="items : cr 
<xs: element ref="items : cr 
<xs : element ref="items : rc 
<xs: element ref ="items : sn 
</xs : sequence> 
</xs : complexType> 
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</xs :element> 
</xs : schema> 

</types> 

< inter face name="retr ieveDe tails Inter f ace" > 

<operation name="retrieve" 

pattern="http://www.w3.org/ns/wsdl/in-out"> 
<input messageLabel="In" element="#none" /> 
<output messageLabel="Out" 

element="wdetails : reservationDetails" /> 

</operation> 
</interf ace> 
</description> 



4. Advanced Topics II: Extensibility and Predefined 
Extensions 

4.1 Extensibility 

WSDL 2.0 provides an open content model, which allows XML elements and 
attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a 
WSDL 2.0 document. The qualified name (complete with namespace URI) of the 
extension element or attribute acts as an unambiguous name for the semantics of 
that extension. 

The namespace URI of the extension element should be dereferenceable to a 
document that describes the semantics of that extension. As of this writing, there is 
no generally accepted standard for what kind of document that should be. However, 
the W3C TAG has been discussing the issue (see TAG issue 
namespa ceDocu men t-8) and is likely to provide guidance at some point. 

4.1.1 Optional Versus Required Extensions 

Extensions can either be required or optional. 

An optional extension is one that the client may either engage or ignore, entirely at 
its discretion, and is signaled by wsdi:required=" false" or the absence of the 
wsdi: required attribute (because it defaults to false). Thus, a WSDL 2.0 processor, 
acting on behalf of the client, that encounters an unknown optional extension can 
safely ignore it and continue to process the WSDL 2.0 document. However, it is 
important to stress that optional extensions are only optional to the client — not the 
service. A service must support all optional and required extensions that it 
advertises in its WSDL 2.0 document. 

A required extension is one that must be supported and engaged by the client in 
order for the interaction to proceed properly, and is signaled by 
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wsdi:required="true". If a WSDL 2.0 processor, acting on behalf of the client, 
encounters a required extension that it does not recognize or does not support, 
then it cannot safely continue to process the WSDL 2.0 document. In most 
practical cases, this is likely to mean that the processor will require manual 
intervention to deal with the extension. For example, a client developer might 
manually provide an implementation for the required extension to the WSDL 2.0 
processor. 

4.2 Defining New MEPs 

As we mentioned in 2.4.4.3 U nderstanding M essag e Exchange Patterns 
( MEPs) , even though the 8 MEPs defined by WSDL 2.6 are intended to cover 
most of the common use cases, there are situations that require new MEPs to be 
defined. In this section, we will explain how new MEPs can be defined to address 
special business requirements. 

Following the wild success of its reservation service, GreatH discovered that it 
could radically increase tourist interest by supplying information on weather 
conditions, both to travel agents and to the general touring public. This produced a 
challenge for the service implementers: how could this information be supplied to 
interested parties without requiring knowledge of web service technology 
specifically, and of computers generally? At issue was the desire to provide 
asynchronous updates to unsophisticated customers without incurring onerous 
overheads for technical support. 

The solution adopted was to create a standard mailing list, and to make available 
a small cross-platform web service client (actually, a subscriber) that could be 
installed on any computer with POP or IMAP access to a mailbox. The mailbox, 
once signed up for the mailing list, could either be processed as "dedicated" (to 
the GreatH weather service; travel agents did this) or as "general purpose" (in 
which case the application would only examine those emails that contained 
Subject headers associated with the service). This required development of a 
binding to email, which is out of scope for this example, but the resulting WSDL 
2.0 was otherwise quite straightforward. 

Note: the email binding in use here supports publish/subscribe, by supporting the 
robust-out-only MEP as well as the client/server style in-out used for subscribing 
and unsubscribing. Details of this binding would require a document as long as the 
primer, so play along. 



Example 4-1. Weather Notification Service (Initial) 

<?xrnl version="l . 0" encoding="utf-8" ?> 

description xmlns="http: //www . w3 . org/ns/wsdl " 

targetNamespace="http: / /greath . example . com/20 04 /wsdl/weathSvc.wsdl' 
xmlns : tns="http : //greath. example . com/ 2 0 04 /wsdl /weathSvc . wsdl" 
xmlns :wsoap="http : //www . w3 . org/ns/wsdl/soap" 
xmlns : email="http : //www . example . com/webservices/ email" > 

<types> 
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</ types> 

<interf ace name= "weather In terf ace" > 

<operation name="opSubscribeWeather " 

pattern="http: //www.w3 . org/ns/wsdl/in-out"> 
<input element=". . . " /> 
<output element=" . . ." /> 
</ operation> 

<operation name="opUnsubscribeWeather" 

pattern="http: //www.w3 . org/ns/wsdl/in-out"> 

<output element=". . ." /> 

<input element=". . . " /> 
</operation> 

<operation name="opNotif yWeather " 

pattern="http: //www . w3 . org/ns/wsdl/ rebus t-out-only"> 
<output element=". . . " /> 
</operation> 
</interf ace> 

<binding name="weatherMailingListBinding" 
inter face="tns : weather Interface 
type="http: //www. w3 .org/ns/wsdl /soap" 

wsoap:protocol="http : //www . example . com/bindings /email "> 
</binding> 

<service name="weatherService" 

inter face="tns : weather Inter face" > 
<endpoint name="greatHWeatherList" 

binding="tns :weatherMailingListBinding" 
address="mailto : weather-ownerSgreath . example . com" /> 

</service> 
</description> 



Note: in the example, the messageLabels of all input and output elements have 
been elided, as they are not necessary to disambiguate (but note that the order of 
input and output elements is not significant). 

Unfortunately, the service was soon highjacked for the purpose of annoyment. 
Repeatedly, hotels in less salubrious climes, and the victims of various natural 
climactic disasters (hurricanes, tornadoes) found themselves signed up to receive 
material full of incomprehensible pointy brackets. They complained to GreatH, who 
complained to their service designers. 

Applying public key infrastructure to solving the problem was immediately rejected 
as too complex and too heavyweight. Analysis showed that the problem was simply 
to verify that the address requesting information actually wanted that information. 
Consequently, a new message exchange pattern was defined. 

4.2.1 Confirmed Challenge 

This pattern consists of two or more messages in order as follows: 
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1. A message: 

o indicated by a Message Label component whose message label is 

"Request" and direction is "in" 
o received from some node N1 

2. A message: 

o indicated by a Message Label component whose message label is 

"Challenge" and direction is "out" 
o sent to some node N2 (which may be the same node as N1) 

3. An optional message: 

o indicated by a Message Label component whose message label is 

"Confirmation" and direction is "in" 
o received from node N2 

4. An optional message: 

o indicated by a Message Label component whose message label is 

"Response" and direction is "out" 
o sent to node N2 

This pattern uses the rule Message Triggers Fault. 

An operation using this message exchange pattern has a pattern property with the 
value "http://www.example.com/webservices/meps/confirmed-challenge". 
Once the MEP had been defined (and the email binding specification appropriately 
modified to indicate that this was a supported MEP), the service was redefined 
and redeployed. Only the changed operations are shown in the excerpt below. 

Example 4-2. Weather Notification Service (Revised) 

<?xml version="l . 0" encoding="utf-8 " ?> 

<description xmlns="http : //www.w3 . org/ns/wsdl " 

targetNamespace="http : / /greath . example . com/ 2 004 /wsdl/weathSvc . wsdl' 
xmlns : tns="http : / /greath . example . com/20 0 4 /wsdl /weathSvc .wsdl" 
xmlns : wsoap="http : //www .w3. org/ns/wsdl /soap" 
xmlns :email="http : //www. example . com/webservices /email " > 

-cinterface name="weather Inter f ace "> 

<operation name="opSubscribeWeather " 

pattern="http: //www .example . com/webservices/meps/conf i 
<input messageLabel="Request" element=". . ." /> 
<output messageLabel="Challenge" element=". . . " /> 
<input messageLabel="Conf irmation" element=" . . . " /> 
<output messageLabel="Response" element=" . . . " /> 
</operation> 

<operation name="opUnsubscribeWeather" 

pattern="http: //www. example . com/webservices/meps/conf i 
<output messageLabel="Challenge" element=". . . " /> 
<output messageLabel="Response" element=". . . " /> 
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<input messageLabel="Conf irmation" element=". . . " /> 
<input messageLabel="Request" element=" . . ." /> 
</ operation> 

</interf ace> 



</description> 



Note: in the second example, the input and output examples are not in the 
sequence in which they occur in the pattern; this illustrates that the sequence is not 
significant. Note, however, that for this pattern, the messageLabel attribute is 
required on every input and output element. 

4.3 RPC Style 

Section 2.4.4.1 Operation Attributes mentioned that the (optional) style attribute 
of an interface operation is used to indicate that the operation conforms to a 
particular pre-defined operation style, or set of constraints. Actually, if desired the 
style attribute can hold a list of URIs, indicating that the operation simultaneously 
conforms to multiple styles. 

Operation styles are named using URIs, in order to be unambiguous while still 
permitted new styles to be defined without requiring updates to the WSDL 2.0 
language. WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines three such operation 
styles; one of these is the RPC Style (RPC Style). 

The RPC Style is designed to facilitate programming language bindings to WSDL 
2.0 constructs. It allows a WSDL 2.0 interface operation to be easily mapped to a 
method or function signature, such as a method signature in Java(TM) or C#. RPC 
Style is restricted to operations that use the In-Out or In-Only MEPs (see 2.4.4.3 
UMerstanding Message Exchange Patterns (MEPs)). 
A WSDL 2.0 document makes use of the RPC Style in an interface operation by 
first defining the operation in conformance with all of the RPC Style rules, and then 
setting that operation's style attribute to include the URI that identifies the RPC 
Style, thus asserting that the operation does indeed conform to the RPC Style. 
These rules permit the input and output message schemas to map conveniently to 
inputs and outputs of a method signature. Roughly, input elements map to input 
parameters, output elements map to output parameters, and elements that appear 
both in the input and output message schemas map to input/output parameters. 
WSDL 2.0 Part 2 section "RPC Style" provides full details of the mapping rules and 
requirements. 

The RPC Style also permits the full signature of the intended mapping to be 
indicated explicitly, using the wr P c: signature attribute defined in WSDL 2.0 Part 2 
section "wrpcisig nature Extension ". This is an (optional) extension to the WSDL 2.0 
language whose value designates how input and output message schema elements 
map to input and output parameters in the method signature. 
The example below illustrates how RPC Style may be used to designate a 
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signature. This example is a modified version of the GreatH reservation service. In 
particular, the interface and types sections have been modified to specify and 
conform to the RPC Style. 

Example 4-3. Specifying RPC Style 



<types> 

<xs : element name="checkAvailability"> 
<xs : complexType> 
<xs : sequence> 

<xs: element name="checkInDate" type="xs : date"/> 
<xs:element name="checkOutDate" type="xs : date" /> 
<xs: element name="roomType" type="xs : string"/> 
</xs : sequence> 
</xs : complexType> 
</xs:element> 

<xs : element name="checkAvailabilityResponse"> 
<xs : complexType> 
<xs : sequence> 

<xs: element name="roomType" type="xs : string" /> 
<xs: element name="rateType" type="xs : string" /> 
<xs:element name="rate" type="xs :double"/> 
</xs : sequence> 
</xs : complexType> 
</ xs : element> 

</ types> 

<interface name = "reservationlnterf ace" > 

<operation name=" checkAvailability" 

pattern="http: //www.w3 . org/ns/wsdl/in-out" 
style="http: //www. w3 . org/ns/wsdl/rpc" 
wrpc : signature= 

"checklnDate #in checkOutDate #in roomType #inout rateType #out 
<input messageLabel=" In" 

element="tns : checkAvailability" /> 
<output messageLabel="Out" 

element="tns : checkAvailabilityResponse" /> 

</operation> 
</interf ace> 



Note that the interface operation's name "checkAvailability", is the same as the 
localPart of the input element's QName, "tns: checkAvailability". This is one of 
the requirements of the RPC Style. The name of the operation is used as the 
name of the method in a language binding, subject to further mapping restrictions 
specific to the target programming language. In this case, the name of the method 

WOUld be "checkAvailability". 
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The local children elements of the input element and output element designate the 
parameters and the return type for a method call. Note that the elements 
checkinDate, checkoutDate are input parameters, however the element roomType 
is an in-out parameter, as it appears both as a local element child of both input 
and output elements. This indicates that the reservation system may change the 
room type requested based on availability. 

The reservation service also returns a rate type for the reservation, such as "rack 
rate". The return value for the method is designated as the "rate" element. 
Based on the value of the wrpc: signature attribute, the method signature would 
be obtained following the order of the parameters. A sample mapping is provided 
below for the Java(TM) language. This example was created using JAX RPC 1.1 
[ J AX RPC 1.1 ] for mapping simple types to Java types and designated inout and 
output parameters by using Holder classes. 

Example 4-4. Sample Java(TM) Signature for RPC Style 

public interface reservationlnterf ace extends Remote! 

double checkAvailability (java . util . calendar checkinDate, 
java.util. calendar checkOutDate, 
StringHolder roomType, 

StringHolder rateType) throws RemoteException; 

»' i 

Programming languages may further specify how faults are mapped to language 
constructs and their scopes, such as Exceptions, but they are not specific to RPC 
style. 

5. Advanced Topics III: Miscellaneous 

This section covers various topics that may fall outside the scope of WSDL 2.0, 
but shall provide useful background and best practice guidances that may be 
useful when authoring a WSDL 2.0 document or implementing the WSDL 2.0 
specification. 

5.1 Enabling Easy Message Dispatch 

It is desirable for a message recipient to have the capability to uniquely identify a 
message type in order to handle it correctly. The capability of identifying a 
message type is typically used for dispatching purposes within an implementation 
of a web service. Therefore, WSDL authors are recommended to consider how to 
disambiguate message types when they develop their services. 
The context in which a Web service may be deployed plays an important role in 
choosing an appropriate way to disambiguate and identify message types. In a 
typical deployment, an endpoint address may host a single service that is 
described by a WSDL service element. In this case, when XSD is used, assigning 
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unique qualified names of global element declarations as inputs within the 
interface that describes the service would be sufficient to disambiguate the types 
of the messages that are received. However, when endpoint address hosts 
multiple services, in essence supporting several WSDL descriptions, the desire to 
disambiguate message types should be considered within the context of all the 
deployed services, not only within a single interface. 

As explained in 2.4.4.1 Operation Attributes, when XSD is used as the type 
system, a few special tokens can be used for the element attributes. Uniquely 
identifying a message type may become very difficult when: 

• any of these input elements within an interface has a value of "#any"; or 

• more than one of these input elements (see below) has a value of "#none"; 
or 

• the qualified names of the global element declarations that are specified as 
input elements are NOT unique when considered together. 

If any of the three cases above arise, disambiguation mechanisms may be 
provided by means of an extension element (i.e., an element that is not in the 
http://www.w3.org/ns/wsdl namespace), having a wsdhrequired attribute with a 
value of "true". The semantics of such an extension element would indicate the 
mechanism for unambiguously identifing the mechanism that a message sender is 
required to support in order to enable the message recipient to unambiguously 
determine the message received. 

For example, the WS-Addressing [WS-Addressing] specification provides such a 
disambiguation mechanism. It consists of an extension element which may be 
marked as required, and defines a required [action] property whose value is 
always present in a conformant message delivery. The value of the action property 
can be used to disambiguate the message by the receiver and there is a well 
defined way to associate actions to messages in WS-Addressing specifications. 
Further, WS-Addressing also provides an appropriate default action value that 
identifies each message type uniquely. 

When using the HTTP Binding, or when using the SOAP Binding with the SOAP 
Response MEP, there is no SOAP envelope in a request message, and thus 
mechanisms other than unique qualified names of global element declarations, or 
headers such as wsa:Action, must be considered. In these cases, the {address} 
and {http location} properties may be constructed so as to provide a location that 
can be correlated uniquely with an operation. For instance, one could prefix the 
{http location} property with the operation name, or one could ensure that the 
portion of the {http location} preceding the first unescaped "{" character be unique 
per operation. 

5.2 Web Service Versioning 

A WSDL 2.0 document describes a set of messages that a Web service may send 
and receive. In essence, it describes a language for interacting with that service. 
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However it is possible for a Web service to exchange other messages beyond 
those described in a particular WSDL 2.0 document. Often this circumstance 
occurs following an evolution of the client and/or service, and thus an evolution of 
the interaction language. 

How best to manage the evolution (versioning) of Web based systems is, at the 
time of writing, the subject of a wide-ranging debate. However, there are three 
activities within the W3C that are directly relevant to versioning of Web services 
description: 

• The Technical Architecture Group (TAG) has published guidance on the 
extensibility and versioning of data formats in its Web Architecture document 
[Web^Architecture\. There is also a more wide ranging draft finding on 
Versioning and Extensibility [W3C TAG Findin g: Versionin g]. Both of these 
works build upon the technical note on Web Architecture: Extensible 
Languages [Web Arch: Extensible Languages]. 

• The XML Schema Working Group is collecting a series of use cases for 
schema versioning as a part of the Schema 1.1 activity. See XML Schema 
Versioning Use Cases [X ML Schema: Versioning U s e-Cases ], 

• The Guide to Versioning XML Languages using XML Schema 1.1 [Guide to 
Versioning XML Languages using XML Schema 1.1] illustrates some 
techniques for versioning XML languages enabled by features of XML 
Schema 1.1 [XML Schema 1.1]. 

• The Semantic Web Best Pr actice s and Deplo y me nts W orking Group is 
examining how vocabularies may evolve. See [SW VocabManagementNote] 

While incomplete, these activities all agree in one important respect: that 

versioning is difficult, but you should anticipate and plan for change. 

The draft finding on Versioning and Extensibility details two key approaches to 

versioning: 

• compatible evolution; and 

• big bang. 

5,2,1 Compatible Evolution 

In compatible evolution, designers are expected to limit changes to those that are 
either backward or forward compatible, or both: 

Backward compatible 

The receiver behaves correctly if it receives a message in an older version of 
the interaction language. 
Forward compatible 

The receiver behaves correctly if it receives a message in a newer version of 
the interaction language. 
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Since Web services and their clients both send and receive messages, these 
concepts can apply to both parties. However, since WSDL 2.0 is service-centric, 
we will focus on the case of service evolution. 

There are three critical areas in which a service described in WSDL 2.0 my evolve: 

• The service now also supports additional binding. In compatible evolution, 
this should be a safe addition, given that adding a new binding should not 
impact any existing interactions using another transport. 

• An interface supports new operations. Again, in compatible evolution this is 
usually safe, given that adding an additional operation to an abstract 
interface should not impact any existing interactions. 

• The message bodies may include additional data. How the message 
contents may change within a description depends to a large extent upon the 
type system being used to describe the message contents. RelaxNG 
[RELAX NG] has good support for describing vocabularies that ignore 
unknown XML, as does OWL/RDF. XML Schema 1 .0 has limited support for 
extending the description of a message via the xsrany and xsranyAttribute 
constructs. XML Schema 1.1 has been chartered to provide "changes 
necessary to provide better support for versioning of schemas", and it is 
anticipated that this may include improved support for more "open content" 
and therefore better support for compatible evolution of messages. 

• The protocol used to exchange messages may provide mechanisms for 
exchanging data outside of the message body. In the case of SOAP, the 
WSDL 2.0 binding provides the ability to describe application data to be 
exchanged as headers. The SOAP processing model has a very good 
extensibility model with unknown headers being ignored by a receiver by 
default. There is also a mechanism whereby headers which are required as 
a part of an incompatible change may be marked with a 'mustUnderstand' 
flag. Passing additional items as headers may be the only way to compatibly 
evolve messages with fixed bodies. 

5.2.2 Big Bang 

The big bang approach to versioning is the simplest to currently represent in 
WSDL 2.0. In this approach, any change to a WSDL 2.0 document implies a 
change to the document's namespace, a change to the interface implies a new 
interface namespace and a change to the message contents is communicated 
using a new message namespace. This approach has particular benefits where an 
agent may quickly tell if a service has changed by simply comparing the 
namespace value. 

5.2.3 Evolving a Service 

Compatible changes are far more easily managed than incompatible ones: 



http://www.w3.org/TR/2007/WD-wsdl20-primer-20070326/ 



5/8/2007 



Web Services Description Language (WSDL) Version 2.0 Part 0: Primer 



Page 62 of 85 



• With a compatible change the service need only support the latest version of 
a service. A client may continue to use a service adjusting to new version of 
the interface description at a time of its choosing. 

• With an incompatible change, the client receives a new version of the 
interface description and is expected to adjust to the new interface before old 
interface is terminated. Either the service will need to continue to support 
both versions of the interface during the hand over period, or the service and 
the clients are coordinated to change at the same time. An alternative is for 
the client to continue until it encounters an error, at which point it uses the 
new version of the interface. 

5.2.4 Combined Approaches 

It is feasible to combine the "compatible evolution" and "big bang" approaches in a 
variety of different ways. For example, the namespace could be changed when 
message descriptions are changed, but the namespace could stay the same when 
new operations are added. 

While the big bang approach is currently the easiest to implement in WSDL 2.0, it 
can lead to a large number of cloned interfaces that become difficult to manage, 
thus making the compatible approach preferable to many for widely distributed 
systems. In the end, the choice of a versioning strategy for Web services 
described in WSDL 2.0 is left as an exercise to the reader. 

5.2.5 Examples of Versioning and Extending a Service 

5.2.5.1 Additional Optional Elements Added in Content 

The following example demonstrates how content may be extended with additional 
content. The reservation service is changed to a newer version that can accept an 
optional number of guests parameter. The service provider wants existing clients 
to continue to be able to use the service. The author adds the element into the 
schema as an optional element. 



Example 5-1. XML Schema with Optional Elements 

<xs : complexType name="tCheckAvailability"> 
<xs : sequence> 

<xs:element name="checkInDate" type="xs : date" /> 
<xs : element name="checkOutDate" type="xs :date"/> 
<xs:element name="roomType" type="xs : string" /> 

<xs: element name="numberOf Guests" type="xs : integer " minOccurs="0"/ 
<xs:any namespace="##other" processContents="lax"/> 
</xs : sequence> 
</xs : complexType> 



The author has the choice of keeping the same namespace or using a different 
namespace for the additional content and the existing content. In this scenario, it is 
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a compatible change and the author decides to keep the same namespace. This 
allows existing clients to interact with a new service, and it allows newer clients to 
interact with older services. 

5.2.5.2 Additional Optional Elements Added to a Header 

Another option is to add the extension as a header block. This is accomplished by 
defining an element for the extension and adding a header element that 
references the element into the binding operation as child of the input. 



Example 5-2. Additional optional elements added to a SOAP header 

<xs: element name="NumberOf Guests" type="tNumberOf Guests"/> 
<xs : complexType name="tNumberOf Guests "> 
<xs : sequence> 

<xs:element name="numberOf Guests " type="xs : integer " minOccurs="C 
</xs : sequence> 
</xs : complexType> 

<binding name=" reservationSOAPBinding" 

interf ace="tns : reser vat ion Inter face" 
type="http : //www. w3 . org/ns/wsdl/soap" 

wsoap: protocols "http : //www.w3 . org/2 00 3/ 05/ soap/bindings /HTTP/ "> 

<operation ref="tns : opCheckAvailability"> 
<input> 

<wsoap:header element="tns : NumberOf Guests " /> 
</input> 
</operation> 

</binding> 



It is also possible for the header to be marked with soap:mustUnderstand set to 
true. The HTTP Binding has similar functionality though without a mustUnderstand 
attribute. 

5.2.5.3 Additional Mandatory Elements in Content 

This following example demonstrates an extension with additional content. The 
reservation service requires a number of guests parameter. The service provider 
wants existing clients to be unable to use the service. The author adds the 
element into the schema as a mandatory element. 



Example 5-3. Additional Mandatory Elements in Content 


<xs : complexType i 


iame="tCheckAvailabilityV2"> 


<xs : sequence 




<xs: element 


name="checkInDate" type="xs : date"/> 


<xs: element 


name="checkOutDate" type="xs : date"/> 


<xs : element 


name="roomType" type="xs : string"/> 


<xs : element 


name="numberOf Guests" type="xs : integer"/> 
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<xs:any namespace="##other" processContents="lax"/> 
</xs : sequence> 
</xs : complexType> 



The author has the choice of keeping the same namespace or using a different 
namespace for the additional content and the existing content. In this scenario, it is 
an incompatible change and the author decides to use a new name but the same 
namespace. This type is then used in the interface operation, and then binding and 
service endpoints. 

5.2.5.4 Additional Optional Operation Added to Interface 

Section 2.4.2 Interface Inheritance shows another type of versioning or extension, 
where the reservation Interface extends the MessageLog Interface. By definition of 
interface inheritance, a client that understands just the MessageLog Interface will 
continue to work with the reservationlnterface, that it is backwards compatible. 

5.2.5.5 Additional Mandatory Operation Added to Interface 

Often mandatory operations are added to an interface. The Hotel service decides to 
add an operation to the reservation service which is a confirmation. The Hotel 
service requires that all clients upgrade to the new interface to use the service. 
They have a variety of options for indicating that the old interface is deprecated. 
By the definition of interface inheritance, they cannot use interface inheritance for 
defining the extension. 

zxample 5-4. Additional Mandatory Operation Added to the Interface 

<interf ace name="reservationWithConf irmation" extends="cc : creditCardFault 

<operation name="makeReservation"> 

<input messageLabel="In" element="ghns :makeReservation" /> 
<output messageLabel="Out" element="ghns :makeReservationResponse" 
<outfault ref =" invalidDataFaul t " messageLabel="Out" /> 
<outfault ref ="cc : cancelledCreditCard" messageLabel="Out" /> 
<outfault ref="cc:expiredCreditCard" messageLabel="Out" /> 
<outfault ref ="cc : invalidCreditCardNumber" messageLabel="Out" /> 
<outfault ref ="cc : invalidExpirationDate" messageLabel="Out" /> 

</operation> 

<ope ration name="conf irmReservation"> 

<input messageLabel="In" element="ghns :makeReservationResponse" / 
<output messageLabel="Out" element="ghns : conf irmReservationRespon 
<outfault ref ="expiredReservation" messageLabel="Out" /> 

</operation> 
</interface> 



This interface cannot be bound and deployed at the existing URI and indicate 
incompatibility, as the service will still accept the makeReservation request. 
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Changing the name of the interface from reservation to 
reservationWithConfirmation or changing the name of the operation from 
makeReservation to makeReservationV2 does not affect the messages that are 
exchanged. Thus it can't be used as a mechanism for indicating incompatibility. To 
indicate incompatibility, a change must be made to something that appears in the 
message. For a SOAP over HTTP request, the list is roughly the URI, the SOAP 
Action HTTP Header, or the Message content. 

5.2.5.6 Indicating Incompatibility by Changing the Endpoint URI 

To indicate incompatibility, the URI of the Hotel Endpoint can be changed and 
messages send to the old Endpoint return a Fault. 

5.2.5.7 Indicating Incompatibility by Changing the SOAP Action 

The SOAP Action can be set for the makeReservation request, and making it 
different than the earlier version should indicate incompatibility. 

Example 5-5. Indicating Incompatibility by changing the SOAP Action 

<binding name="reservationSOAPBinding" 

interf ace="tns : reservationlnterf ace" 
type="http : / /www . w3 . org/ ns/wsdl/soap" 

wsoap :protocol="http:/ /www. w3 .org/2 00 3/ 0 5/ soap/bindings/HTTP/ "> 
<operation ref ="tns :makeReservation" 

wsoap: action="tns :makeReservationV2"/> 



Note that this mechanism is applicable on a per-binding basis. The SOAP HTTP 
Binding provides for setting Action, but other bindings may not provide such a 
facility. 

5.2.5.8 Indicating Incompatibility by Changing the Element Content 

The namespace or name of the makeReservation element can be changed, and 
then the interface and bindings changed. To indicate incompatibility, requests 
using the old makeReservation QName should probably return a fault. The new 
interface, with a changed makeReservation, is: 



Example 5-6. Indicating incompatibility by changing the element content 

<xs : element name="ghns2 : makeReservation" type="ghns : tmakeReservation" /> 
<interface . . . > 

<operation name= "makeReservation "> 

<input messageLabel="In" element="ghns2 : makeReservation" /> 
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</interf ace> 




The binding and service endpoints require no change. 

Finally, the service could also provide an interface for ghns:makeReservation that 
only returns a fault. 

5.3 Describing Web Service Messages That Refer to Other Web 

Services 

Hyperlinking is one of the defining characteristics of the Web. The ability to navigate 
from one Web page to another is extremely useful. It is therefore natural to apply 
this capability to Web services. This section describes references to endpoints and 
services, which are the Web service analogs of document hyperlinks. 
A reference to an endpoint is an element or attribute that contains the address of a 
Web service endpoint. A reference to a service is an element or attribute that 
contains one or more references to the endpoints of a service. If the interface or 
binding that the service or endpoint implements is known at description time, it may 
be useful to add this information to the WSDL 2.0 document that describes the Web 
service. This is accomplished by using the wsdix: interface or wsdix: binding 
attribute to annotate the XML Schema component that defines the message. 
One may wonder, from a Web architectural point of view, why anything more than a 
URI would be needed to reference a Web service. Indeed, a reference to a service 
does make use of one or more URIs to indicate the endpoint addresses of a 
service. However, it may also include additional metadata about that service, such 
as the WSDL 2.0 interface and binding that the service supports. 
References to services and endpoints will be illustrated by expanding the GreatH 
example already discussed. 

5.3.1 The Reservation Details Web Service 

When designing a Web application it is natural to give each important concept a 
URI. In the GreatH hotel reservation system, the important concepts are 
reservations, so we begin our design by assigning a URI to each reservation. Since 
each reservation has a unique confirmation number, e.g OMX736, we create a URI 
for each reservation by appending the confirmation number to a base URI, e.g. 
http://greath.example.com/2004/reservation/OMX736. This URI will be the endpoint 
address for a Reservation Details Web service that can retrieve and update the 
state of a reservation. Exampl e 5-7 shows the format of the reservation detail. 

Example 5-7. Detail for Reservation OMX736 

<?xml version="l . 0" encoding="UTF-8" ?> 
<reservationDe tails 

xmlns="http: / /greath. example . com/2004 /schemas /reservationDetails " 

<conf irmationNumber>OMX736</conf irmationNumber> 
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<checkInDate>2005-06-0K/checkInDate> 
<checkOutDate>2005-06-03</checkOutDate> 
<roomType>single</roomType> 
<smoking>f alse</smoking> 

</reservationDetails> 

The Reservation Details Web service provides operations for retrieving and 
updating the detail for a reservation. Example 5 -8 shows the description for this 
Web service. Note that there is no service element in this description since the set 
of reservations is dynamic. Instead, the endpoints for the reservations will be 
returned by querying the Reservation List Web service. 

Example 5-8. The Reservation Details Web Service Description: 
eservationDetails. wsdl 

<?xml version="l . 0" encoding="utf-8 " ?> 
<description 

xmlns="http: //www. w3.org/ns/wsdl" 

targe tNamespace="http : //greath . example . com/2 0 04 /service s/reservat 
xmlns : tns="http : //greath . example . com/2 0 04 /service s/reservat ionDet 
xmlns : wdetails="http: / /greath . example . com/ 2 00 4/ schemas/reservatio 
xmlns :wsoap="http : //www. w3 . org /ns/ wsdl /soap" 
xmlns :xs="http: //www. w3 . org/2001 /XMLSchema"> 

<documentation> 

This document describes the GreatH Reservation Details We: 
services. Use these services to retrieve or update reserv 
details. Each reservation has its own service and endpoin 
obtain the reference for a reservation service, make a re 
the GreatH Reservation List Web service. See 
reservationList .wsdl for a description of the Reservation 
Web service. 

</documentation> 

<types> 

<xs : import 

namespace="http : / /greath . example . com/20 04 /schemas 
schemaLocation="reservationDetails .xsd" /> 

</types> 

•cinterface name=" reservationDe tails Inter f ace" > 

<operation name="retrieve" 

pattern="http : //www. w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" element="#none" /> 
<output messageLabel="Out" 

element="wdetails : reservationDetails" /> 

</operation> 

<operation name="update" 

pattern="http : //www . w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" 

element="wdetails : reservationDetails" /> 
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<output messageLabel="Out" 

element="wdetails : reservationDetails" /> 

</operation> 
</interface> 

<binding name=" reservationDetailsSOAPBinding" 

interf ace="tns : reservationDetailsInterf ace" 
type="http: //www. w3 . org/ ns/wsdl/ soap" 

wsoap:protocol="http: //www. w3 .org/2 0 03/05/soap/bindings/H 

<operation ref="tns : retrieve" 

wsoap:mep="http: //www. w3 .org/2003 /05/soap/mep/req 

<operation ref="tns : update" 

wsoap:mep="http: //www. w3 . org/2 0 03/05/soap/mep/req 

</binding> 
'description> 

Example 5-9 shows the XML schema elements that are used in this Web service. 



Example 5-9. The Reservation Details Web Service XML Schema: 
eservationDetails. xsd 



<?xml version="l . 0" encoding="UTF-8"?> 
<schema xmlns="http : //www . w3 . org/2 001/XMLSchema" 
element FormDef ault=" qualified" 

targetNamespace="http: //greath. example . com/2004 /schemas/reservati 

xmlns : tns="http : //greath . example . com/2 0 04 /schemas/reservationDeta 

xmlns : wdetails = "http : //greath . example . com/2 0 04/ service s/reservati 

xmlns :wsdli="http: //www. w3 . org/ns/wsdl- instance" 

xmlns :wsdlx="http: //www. w3 . org/ns/wsdl -extensions" 

wsdli : wsdlLocation="http : //greath . example . com/ 2 00 4/ services /reser 

<element name="conf irmationNumber " type="string" /> 

<element name="checkInDate" type="date" /> 

<element name="checkOutDate" type="date" /> 

<element name=" reservationDetails "> 
<complexType> 

<sequence> 

<element ref="tns : conf irmationNumber" /> 
<element ref ="tns : checklnDate" /> 
<element ref="tns : checkOutDate" /> 
<element name="roomType" type="string" /> 
<element name="smoking" type="boolean" /> 
</ sequence> 
</complexType> 
</element> 

<simpleType name="reservationDetailsSOAPEndpointType" wsdlx:bindi 
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<restriction base="anyURI"/> 

</simpleType> 

<element name="reservationDetailsSOAPEndpoint" type="tns : reservat 

<element name=" reservat ionDetailsService"> 
<annotation> 

<documentation> 

This element contains references to the R 
Details Web Service endpoints for this re 
</ documentation> 
</annotation> 
<complexType> 

<sequence> 

<element name="soap" type="tns : reservatio 
<element name="secure-soap" type="tns : res 
</sequence> 
</complexType> 
</element> 

</schema> 



This XML schema contains the usual definitions for the elements that appear in the 
messages of the Web service. For example, the reservationDetaiis element is 
used in the messages of the retrieve and update operations. In addition, the 
schema defines the simple type reservationDetaiissoAPEndpointType which is 
based on xs:anyuRi and has the annotation wsdix: binding = 

"wdetails:reservationDetailsSOAPBinding" which means that the URI is the 

address of a Reservation Details Web service endpoint that implements the 

wdetails : reservationDetailsSOAPBinding binding. Note that the 

wsdii:wsdiLocation attribute is used to define the location of the WSDL 2.0 
document that defines the wdetails : reservationDetailsSOAPBinding binding. This 
annotated simple type is used to define the reservationDetaiissoAPEndpoint 
element which will be used in the Reservation List service. 

5.3.2 The Reservation List Web Service 

Since the set of reservations changes as reservations are made and cancelled, the 
Reservation Detail endpoints are not described in a fixed WSDL 2.0 document. 
Instead they are returned as references to endpoints in response to requests made 
on a Reservation List Web service. The endpoint address for the Reservation List 
service will be http://greath.example.com/2004/reservationList. 
Example 5-10 shows the format of the response from the Reservation List service. 



zxample 5-10. Response from the Reservation List Web Service 

<?xml version="l . 0" encoding="UTF-8"?> 

<reservationList 

xmlns="http : //greath. example.com/2 004/schemas/reservationList" 
xmlns : details="http : / /greath . example . com/2004 / schemas/ reservation 
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<reservation> 

<details : conf irmationNumber>HSG635</details : conf irmationN 
<details:checkInDate>2 005-0 6-27</details:checkInDate> 
<details : checkOutDate>2005-06-28</details : checkOutDate> 
<details : reservationDetailsSOAPEndpoint> 

http://greath.example.com/2 004/reservation/HSG635 
</details : reservationDetailsSOAPEndpoint> 
</reservation> 

<reservation> 

<details : conf irmationNumber>OMX736</details : conf irmationN 
<details:checkInDate>2 005-0 6-0 K/details : checkInDate> 
<details : checkOutDate>2005-06-03</details : checkOutDate> 
<details : reservationDetailsSOAPEndpoint> 

http: //greath. example .com/2 004 /reservation/OMX73 6 
</details : reservationDetailsSOAPEndpoint> 
</reservation> 

<reservation> 

<details : conf irmationNumber>WUH663</details : conf irmationN 
<de tails : checkInDate>2 005-0 6-1 1< /details : checkInDate> 
<details : checkOutDate>2 005-0 6-1 5</details : checkOutDate> 
<details : reservationDetailsSOAPEndpoint> 

http://greath.example.com/2 0 04/reservation/WUH663 
</details : reservationDetailsSOAPEndpoint> 
</reservation> 

</reservationList> 



Here, the <details:reservationDetailsSOAPEndpoint> elements Contain 

references to the Reservation Details Web service endpoints for the reservations 
HSG635, OMX736, and WUH663. 

Examp le 5-1 1 shows the description of the Reservation List Web service. Note that 
it contains operations to retrieve the entire list and to query for a list of reservations 
by confirmation number, check-in date, and check-out date. In each case, the 
operation returns a list of reservations. 



zxample 5-11. The Reservation List Web Service Description: reservationList.wsdl 



<?xml version="l . 0" encoding="utf-8 " ?> 
<description 

xmlns="http : / /www . w3 . org/ns/wsdl " 

targetNamespace="http : //greath . example . com/2 004 /services /re servat 
xmlns : tns="http : //greath . example . com/ 2 0 04 / services /reservationLis 
xmlns : detail s= "http: //greath. example . com/ 2 004 /schemas/ reservation 
xmlns : lis t= "http: //greath . example . com/ 2 0 04 /schemas /reservationLis 
xmlns :wsoap=" http : //www. w3 . org/ns/wsdl /soap" 
xmlns :xs="http: //www. w3.org/2001 /XMLSchema"> 

<documentation> 

This document describes the GreatH Reservation List Web 
services. Use this service to retrieve lists of reservati 
based on a variety of search criteria. 

</ documentation> 
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<types> 

<xs : import 

namespace="http : //greath . example. com/2 004 /schemas 
schemaLocation="reservationDetails . xsd" /> 
<xs : import 

namespace="http : //greath . example. com/2 004 /schemas 
schemaLocation="reservationList .xsd" /> 

</types> 

<interf ace name= " reservat ionList I nterf ace" > 

<operation name="retrieve" 

pattern="http: //www.w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" element="#none" /> 
<output messageLabel="Out" element="list : reservat 

</operation> 

<operation name="retrieveByConf irmationNumber " 

pattern="http: //www . w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" 

element="details : conf irmationNumber " /> 
<output messageLabel="Out" element="list : reservat 

</ operation> 

<operation name="retrieveByCheckInDate" 

. pattern="http: //www. w3 . org/ns/wsdl/in-out"> 
<input messageLabel="In" element="details : checkln 
<output messageLabel="Out" element="list : reservat 

</ operation> 

<operation name="retrieveByCheckOutDate" 

pattern="http : //www . w3 . org/ns/wsdl/in-out"> 
<input messageLabel=" In" element="details : checkOu 
<output messageLabel="Out" element="list : reservat 

</operation> 

</interface> 

<binding name=" reservat ionListSOAPBinding" 

interf ace="tns : reservationListlnterf ace" 
type="http: //www. w3 . org/ns/wsdl/soap" 

wsoap :protocol="http : //www . w3 . org/ 2 003/ 05/ soap /bindings /H 

<operation ref="tns : retrieve" 

wsoap :mep="http : //www . w3 . org/2003/05/soap/mep/req 

<operation ref="tns : retrieveByConf irmationNumber" 

wsoap :mep="http: //www . w3 . org/2 003/0 5/ soap/mep/req 

<operation ref="tns : retrieveByChecklnDate" 

wsoap :mep="http : / /www . w3. org/2003/05/ soap/mep/ req 

<operation ref="tns : retrieveByCheckOutDate" 

wsoap :mep="http : / / www . w3. org/2003/ 05/soap/mep/req 
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<service name="reservationListService" 

interf ace="tns : reservationListlnterf ace"> 

<endpoint name="reservationListEndpoint" 

binding="tns : reservationListSOAPBinding" 
address="http : //greath. example . com/2 004 /reservati 



</service> 
</description> 



Examp l e 5-12 shows the schema for the messages used in the Reservation List 
Web service. 

Example 5-12. The Reservation List Schema: reservationList.xsd 

<?xml version="l . 0" encoding="UTF-8 " ?> 
I < schema xmlns="http : //www . w3 . org/2 001 /XMLSchema" 
elementFormDef ault= "qualified" 

targe tNamespace="http : //greath . example . com/ 2 0 04 /schemas/ reservati 
xmlns : tns="http : //greath . example . com/20 04 /schemas/reservationList 
xmlns : detail s = "http : //greath . example . com/2 0 04 /schemas/ reservati on 
xmlns : wsdli="http : //www. w3 . org/ns/wsdl- instance "> 



<import 



espace="http : //www . w3 . org/ns/wsdl-insta: 



namespace="http: //greath. example . com/ 20 04 / schemas /reserva 
schemaLocation="reservationDe tails . xsd" /> 

<element name="reservation"> 
<annotation> 

<documentation> 

A reservation contains the confirmation n 
and check-out dates, and a reference to a 
Details Web service. 
</documentation> 
</annotation> 
<complexType> 

<sequence> 

<element ref="details : conf irmationNumber " 
<element ref ="details : checklnDate" /> 
<element ref ="details : checkOutDate" /> 
<element ref ="details : reservationDetailsS 
</sequence> 
</complexType> 
</element> 

<element name="reservationList"> 
<annotation> 

<documentation> 

A reservation 



contains a sequence of 
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reservations . 

</documentation> 
</annotation> 
<complexType> 

<sequence> 

<element ref="tns : reservation" minOccurs= 

maxOccurs=" unbounded "> 
</element> 
</sequence> 

<attribute ref ="wsdli : wsdlLocation" /> 
</complexType> 
</element> 

</schema> 



In the preceding example, there was a single endpoint associated with each 
Reservation Detail Web service. Suppose GreatH hotel decided to provide a 
second, secure endpoint. In this case, references to services would be used to 
collect together the endpoints for each reservation. The reservationDetails.xsd 
schema defines the reservationDetaiisservice element for this purpose. It 
contains the nested elements soap and secure-soap which are each of type 
reservationDetaiissoAPEndpointType and therefore contain the address of an 
endpoint that implements the wdetaiis :reservationDetaiissoAPBinding binding. 
Example 5-13 shows an example of a message that contains a reference to the 
service for reservation HGS635. Note that the service contains two endpoints, one 
of which provides secure access to the Reservation Details Web service. 



Example 5-13. A Reference to the Reservation Details Web Service 

<?xml version="l . 0" encoding="UTF-8 " ?> 
< details : reservationDetaiisservice 

xmlns : details="http : //greath . example . com/2004/schemas/reservation 

<details : soap> 

http: //greath. example. com/20 04/ reservation/HSG635 
</ details : soap> 

<details : secure-soap> 

https : //greath. example . com/2 004 /reservation/HSG635 
</details : secure-soap> 

</details : reservationDetailsService> 



5.3.3 Reservation Details Web Service Using HTTP Transfer 

This section presents a variation on the example in 5.3.1 The Reservation Details 
Web Service . It illustrates the use of HTTP transfer operations, GET and PUT, to 
retrieve and update GreatH hotel reservation details using the Representational 
State Transfer (REST) architectural style described by Roy Fielding [REST] . REST 
is a distillation of the architectural properties that Dr. Fielding identified as being 
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vital to the Web's robustness and enormous scalability. 
Since each reservation in our example will have a distinct URI, the Reservation 
Details Web service can be offered using HTTP GET and HTTP PUT. The binding 
would be modified as follows: 



Example 5-14. Reservation Details Web Service Using HTTP Transfer 



<binding name="reservationDetailsHTTPBinding" 
type="http: //www . w3 . org/ns/wsdl/http" 
interf ace="tns : reservationDetailsInterf ace" > 

<operation ref="tns : retrieve" 
whttp:method="GET" /> 

<operation ref ="tns :update" 
whttp:method="PUT" /> 

</binding> 



As with the example in 5.3.1 The Reservation Details Web Service , service and 
endpoint elements are not provided because the Reservation List Web service 
provides the endpoints. 



5.3.4 Reservation List Web Service Using HTTP GET 

This section continues the REST-style example of 5.3.3 Reservation Details Web 
Service Using HTTP Transfer by modifying the example of 5.3.2 T he 
Reservation List Web Service to use HTTP GET. 

The SOAP version of the Reservation List Web service above offers four different 
search operations. These can also be expressed as various parameters in a URI 
used by HTTP GET: 



Example 5-15. Reservation List Web Service Using HTTP GET 



<binding name="reservationListHTTPBinding" 

type="http: //www. w3 .org/ns/wsdl/http" 
interf ace="tns : reservationListlnterf ace" 
whttp:methodDefault="GET"> 

<operation ref ="tns : retrieve" 
whttp: location="" /> 

<operation ref="tns : retrieveByConf irmationNumber " 

whttp : location="reservationList/Conf irmationNumber/ { conf irmationNun 

<operation ref ="tns : retrieveByChecklnDate" 

whttp : location="reservationList/CheckInDate/ { checklnDate/ } " /> 

<operation ref ="tns : retrieveByCheckOutDate" 
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whttp : location="reservationList/CheckOutDate/ { checkOutDate/ } " /> 
</binding> 



<endpoint name="reservationListEndpoint" 
binding="tns : reservationListHTTPBinding" 

address="http: //greath . example . com/20 04 /reservationList" /> 
</service> 



A retrieval by Confirmation Number URI would look like: 

http: //greath. example . com/ 2 004 /reservationList/Conf irmationNumber/HSG635 . 

Alternatively, a single query type may be provided. This query type is a sequence of 
optional items. Any items in the sequence are serialized into the URI query string. A 
query sequence for any of ConfirmationNumber, checklnDate, checkOutDate would 
look like this: 



■xample 5-16. Query Sequence Using a Single Query Type 

<element name="reservationQuery"> 
<annotation> 

<documentation> 

A reservation contains the confirmation number, check-in 
and check-out dates, and a reference to a Reservation 
Details Web service. 
</documentation> 
</ annotation> 
<complexType> 
<sequence> 

<element ref ="details : conf irmationNumber " minOccurs=" 0 " /> 
<element ref ="details : checklnDate" minOccurs=" 0 " />/> 
<element ref ="details : checkOutDate" minOccurs="0"/>/> 
</sequence> 
</sequence> 
</complexType> 
</element> 



The WSDL 2.0 service that offers this type serialized as a parameter would look like 
this: 



xample 5-17. WSDL 2.0 for Using a Single Query Type 



< inter face name=" reservationList Inter f aceWithQuery"> 

<operation name="retrieveByReservationQuery" 

pattern="http: / /www. w3 . org/ns/wsdl/in-out" 
<input messageLabel="In" 

element="details:ReservationQuery" /> 
<output messageLabel="Out" 

element="list : reservationList" /> 
</operation> 
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</ interf ace> 

<binding name="reservationListQueryHTTPBinding" 
type="http: //www. w3.org/ns/wsdl/http" 
interf ace="tns : reservationListlnterf aceWithQuery" 
whttp:methodDefault="GET"> 

<operation ref ="tns : retrieveByReservationQuery" 

whttp: location="reservationList/ {ReservationQuery } } " /> 

</binding> 

<endpoint name="reservationListEndpoint" 

binding="tns : reservationListHTTPBinding" 

address="http : //greath. example . com/2004/reservationList" /> 



Various URIs would be: 

http : //greath . example . com/2 004 /reservationList /ReservationQuery? 
conf irmationNumber=HSG63 5 

http : //greath . example . com/2004 /reservationList/ ReservationQuery? 
checkInDate=06-06-05 . 

It is important to observe that using the URI serialization can result in very flexible 
queries and few operations. The previous discrete SOAP operations are collapsed 
into one "parameterized" operation. 

5.4 Multiple Interfaces for the Same Service 

Suppose a Web service wishes to expose two different interfaces: a customer 
interface for its regular users, and a management interface for its operator. A 
wsdi : service specifies only one wsdkinterface, so to achieve the desired effect the 
service provider would somehow need to indicate a relationship between two 
services. How can a service provider indicate a relationship between services? 
Potential strategies include: 

• Declare both interfaces in the same wsdhdescription element. Although 
WSDL 2.0 does not ascribe any particular significance to the fact that two 
wsdhservices are declared within the same wsdhdescription, an application or 
toolkit could interpret this to mean that they are related in some way. 

• Declare both interfaces in the same wsdktargetNamespace. Again, 
although WSDL 2.0 does not ascribe any particular significance to the fact 
that two wsdhservices are declared within the same wsdktargetNamespace, 
an application or toolkit could interpret this to mean that they are related in 
some way. 

• Add an extension to WSDL 2.0 that links together all services that are 
related in this way. WSDL 2.0's open content model permits extension 
elements from other namespaces to appear in a WSDL 2.0 document. 
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• Declare them in completely separate WSDL 2.0 documents, but use the 
same endpoint address for both. I.e., declare a wsdi: interface and 

wsdi : service for the customer interface in one WSDL 2.0 document, and a 
wsdi : interface and wsdi : service for the management interface in a 
different WSDL 2.0 document, but use the same endpoint address for both. 
(By "different WSDL 2.0 document" we mean that both documents are never 
included or imported into the same WSDL 2.0 descriptions component.) 
Although this approach may work in some circumstances, it means that the 
same endpoint address would be used for two different purposes, which is 
apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web 
architectural principle that different URIs should be used to identify different 
Web resources. (See the Web Architecture [We b Ar chit ectu r e ] section on 
URI collision.) 

• Use inheritance to combine the customer interface and management 
interface into a single, larger wsdhinterface. Of course, this reduces 
modularity and means that the management interface becomes exposed to 
the customers, which is not good. 

Bear in mind that since the above strategies step outside of the WSDL 2.0 
language specifies (and are therefore neither endorsed nor forbidden by the 
WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize 
their semantics. 

The desire to express relationships between services is also relevant to Web 
service versioning, discussed next. 

5.5 Mapping to RDF and Semantic Web 

WSDL 2.0 is a language designed primarily with XML syntax. While XML is almost 
universally understood, it has several issues: 

• The ability to compose two XML documents into one depends on the 
languages of those documents. WSDL 2.0 does not permit Web service 
descriptions in different targetNamespaces to be merged into a single 
(physical) XML document. 

• The ability to extend XML languages with other XML languages depends on 
the languages again. WSDL 2.0 is extremely extensible, but the meaning of 
every single extension in WSDL 2.0 must be defined explicitly. Putting a 
piece of XMI (XML format for UML) into a WSDL 2.0 document may have 
different meaning from putting it into an XHTML document. Therefore XML- 
based extensibility has very high cost if many languages are involved. 

• Similarly, extending another XML language with pieces of WSDL 2.0, while 
possible, has to be defined for all the possible destinations. Putting a WSDL 
2.0 interface element into a UDDI registry may mean a different thing from 
putting that interface element into an XHTML document. 

• Finally, the meaning of a portion of a WSDL 2.0 document is not defined by 
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the WSDL 2.0 specification. While an interface element could form a single 
XML document, it is not a WSDL 2.0 document, so its meaning is largely 
undefined. 

Applications that require such levels of composability (or decomposability) are 
increasingly being based on RDF [RDF], a graph-based knowledge representation 
language, and Web Ontology Language (OWL) [OWL], which can be thought of as 
an advanced schema language for RDF. Effectively, a WSDL 2.0 document 
represented in RDF can be more easily extended with arbitrary RDF assertions 
and the WSDL 2.0 information can be more easily associated with arbitrary other 
knowledge. 

5.5.1 RDF Representation of WSDL 2.0 

WSDL 2.0: Mapping to RDF \WS DL 2 . 0 RDF Mapping ] describes how WSDL 2.0 
constructs can be expressed in RDF using classes of resources (described with an 
ontology expressed in OWL) and assertions over individual resources. As RDF 
represents knowledge using resources and relationships between them, we need 
to turn WSDL 2.0 concepts into this model. This is done as follows. 

1. First, all components in WSDL 2.0 (like Interfaces, Operations, Bindings, 
Services, Endpoints etc., including extensions) are turned into resources 
identified with the appropriate URIs created according to Appendix C IRI- 
References for WSDL 2.0 Comp onents of \WSDL 2.0 Core] . 

2. Further, things are represented as resources: 

a. Element declarations gathered from XML Schema (or similarly, other 
components from other type systems) 

b. Message content models 

c. Message exchange patterns (the URI identifying the MEP is the URI of 
the resource) 

d. Operation styles (similarly to MEPs, the URI of an operation style is the 
URI of the resource) 

3. All the resources above are given the appropriate types using rdftype 
statements (an interface will belong to the class Interface and an operation 
within an interface will belong to the class InterfaceOperation, for example). 

4. All relationships in WSDL 2.0 (like an Operation's belonging to an Interface 
and having a given operation style) are turned into RDF statements using 

appropriate properties, SUCh as operation and operationStyle. 

5.6 Notes on URIs 

5.6.1 XML Namespaces and Schema Locations 

It is a common misperception to equate either the target namespace of an XML 
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Schema or the value of the xmins attribute in XML instances with the location of 
the corresponding schema. Even though namespaces are URIs, and URIs may be 
locations, and it may be possible to retrieve a schema from such a location, this 
does not mean that the retrieved schema is the only schema that is associated 
with that namespace. There can be multiple schemas associated with a particular 
namespace, and it is up to a processor of XML to determine which one to use in a 
particular processing context. The WSDL 2.0 specification provides the processing 
context here via the import mechanism, which is based on XML Schema's term for 
the similar concept. 

5.6.2 Relative URIs 

Throughout this document there are fully qualified URIs used in WSDL 2.0 and 
XSD examples. In some cases, fully qualified URIs were used simply to illustrate 
the referencing concepts. However, the use of relative URIs is allowed and 
warranted in many cases. For information on processing relative URIs, see 
RFC 3986 . 

5.6.3 Generating Temporary URIs 

In general, when a WSDL 2.0 document is published for use by others, it should 
only contain URIs that are globally unique. This is usually done by allocating them 
under a domain name that is controlled by the issuer. For example, the W3C 
allocates namespace URIs under its base domain name, w3.org. 
However, it is sometimes desirable to make up a temporary URI for an entity, for 
use during development, but not make the URI globally unique for all time and 
have it "mean" that version of the entity (schema, WSDL 2.0 document, etc.). 
Reserved Top Level DNS Names [IETF RFC 2606] specifies some URI base 
names that are reserved for use for this type of behavior. For example, the base 
URI "http://example.org/" can be used to construct a temporary URI without any 
unique association to an entity. This means that two people or programs could 
choose to simultaneously use the temporary URI " 

http://example.org/userSchema" for two completely different schemas. As long as 
the scope of use of these URIs does not intersect, then they would be unique 
enough. However, it is not recommended that " http://example.org/" be used as a 
base for stable, fixed entities. 
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